Skip to content
CodeAtlas UI

Display

DataTable

Table with global search, column sorting, pagination and a column visibility toggle, built on TanStack Table.

DataTable lives in its own entry point so that TanStack Table stays out of bundles that do not need it. Install the optional peer first.

bun add @tanstack/svelte-table
 
<script lang="ts">
  import { DataTable, createCaColumnHelper } from "@codeatlasdev/ui/table";
  type User = { name: string };
  const users: User[] = [{ name: "Ana Souza" }, { name: "Bruno Lima" }];

  const col = createCaColumnHelper<User>();
  const columns = col.columns([
    col.accessor("name", { header: "Name", meta: { label: "Name" } }),
  ]);
</script>

<DataTable {columns} data={users} />

There are two modes. In simple mode you pass columns and data and the table searches, sorts and paginates locally. In controlled mode you pass globalFilter, pagination and sorting together with their change handlers, and feed it one page of data plus total, which is what you want for server-side data.

Simple mode

Pass `columns` and `data`. Search, sort and pagination are managed automatically.

12 results
IDNameEmailRoleStatus
1Ana Souzaana@example.comAdminactive
2Bruno Limabruno@example.comDeveloperactive
3Carla Mendescarla@example.comDesignerinactive
4Diego Ferreiradiego@example.comDeveloperactive
5Elena Castroelena@example.comManagerpending
6Felipe Rochafelipe@example.comDeveloperactive
7Gabriela Nunesgabi@example.comDesigneractive
8Henrique Lopeshenrique@example.comAdmininactive
9Isabela Torresisa@example.comDeveloperactive
10Joao Almeidajoao@example.comManagerpending
Rows
1 / 2 · 12
Code
svelte 
<script lang="ts">
  import { DataTable, createCaColumnHelper } from '@codeatlasdev/ui/table';

  interface User {
    id: number;
    name: string;
    email: string;
    role: string;
    status: 'active' | 'inactive' | 'pending';
  }

  const data: User[] = [
    { id: 1, name: 'Ana Souza', email: 'ana@example.com', role: 'Admin', status: 'active' },
    { id: 2, name: 'Bruno Lima', email: 'bruno@example.com', role: 'Developer', status: 'active' },
    { id: 3, name: 'Carla Mendes', email: 'carla@example.com', role: 'Designer', status: 'inactive' },
    { id: 4, name: 'Diego Ferreira', email: 'diego@example.com', role: 'Developer', status: 'active' },
    { id: 5, name: 'Elena Castro', email: 'elena@example.com', role: 'Manager', status: 'pending' },
    { id: 6, name: 'Felipe Rocha', email: 'felipe@example.com', role: 'Developer', status: 'active' },
    { id: 7, name: 'Gabriela Nunes', email: 'gabi@example.com', role: 'Designer', status: 'active' },
    { id: 8, name: 'Henrique Lopes', email: 'henrique@example.com', role: 'Admin', status: 'inactive' },
    { id: 9, name: 'Isabela Torres', email: 'isa@example.com', role: 'Developer', status: 'active' },
    { id: 10, name: 'Joao Almeida', email: 'joao@example.com', role: 'Manager', status: 'pending' },
    { id: 11, name: 'Karina Bastos', email: 'karina@example.com', role: 'Developer', status: 'active' },
    { id: 12, name: 'Lucas Carvalho', email: 'lucas@example.com', role: 'Designer', status: 'active' },
  ];

  const col = createCaColumnHelper<User>();
  const columns = col.columns([
    col.accessor('id', { header: 'ID', meta: { label: 'ID' } }),
    col.accessor('name', { header: 'Name', meta: { label: 'Name' } }),
    col.accessor('email', { header: 'Email', meta: { label: 'Email' } }),
    col.accessor('role', { header: 'Role', meta: { label: 'Role' } }),
    col.accessor('status', { header: 'Status', meta: { label: 'Status' } }),
  ]);
</script>

<div class="wrap"><DataTable {columns} {data} /></div>

<style>
  .wrap { width: 100%; min-width: 0; }
</style>

Controlled mode

Own the state to drive server-side filtering, sorting and pagination.

12 results
IDNameEmailRoleStatus
1Ana Souzaana@example.comAdminactive
2Bruno Limabruno@example.comDeveloperactive
3Carla Mendescarla@example.comDesignerinactive
4Diego Ferreiradiego@example.comDeveloperactive
5Elena Castroelena@example.comManagerpending
Rows
1 / 3 · 12
Code
svelte 
<script lang="ts">
  import { DataTable, createCaColumnHelper } from '@codeatlasdev/ui/table';
  import type { PaginationState, SortingState, Updater } from '@codeatlasdev/ui/table';

  interface User {
    id: number;
    name: string;
    email: string;
    role: string;
    status: 'active' | 'inactive' | 'pending';
  }

  const allData: User[] = [
    { id: 1, name: 'Ana Souza', email: 'ana@example.com', role: 'Admin', status: 'active' },
    { id: 2, name: 'Bruno Lima', email: 'bruno@example.com', role: 'Developer', status: 'active' },
    { id: 3, name: 'Carla Mendes', email: 'carla@example.com', role: 'Designer', status: 'inactive' },
    { id: 4, name: 'Diego Ferreira', email: 'diego@example.com', role: 'Developer', status: 'active' },
    { id: 5, name: 'Elena Castro', email: 'elena@example.com', role: 'Manager', status: 'pending' },
    { id: 6, name: 'Felipe Rocha', email: 'felipe@example.com', role: 'Developer', status: 'active' },
    { id: 7, name: 'Gabriela Nunes', email: 'gabi@example.com', role: 'Designer', status: 'active' },
    { id: 8, name: 'Henrique Lopes', email: 'henrique@example.com', role: 'Admin', status: 'inactive' },
    { id: 9, name: 'Isabela Torres', email: 'isa@example.com', role: 'Developer', status: 'active' },
    { id: 10, name: 'Joao Almeida', email: 'joao@example.com', role: 'Manager', status: 'pending' },
    { id: 11, name: 'Karina Bastos', email: 'karina@example.com', role: 'Developer', status: 'active' },
    { id: 12, name: 'Lucas Carvalho', email: 'lucas@example.com', role: 'Designer', status: 'active' },
  ];

  const col = createCaColumnHelper<User>();
  const columns = col.columns([
    col.accessor('id', { header: 'ID', meta: { label: 'ID' } }),
    col.accessor('name', { header: 'Name', meta: { label: 'Name' } }),
    col.accessor('email', { header: 'Email', meta: { label: 'Email' } }),
    col.accessor('role', { header: 'Role', meta: { label: 'Role' } }),
    col.accessor('status', { header: 'Status', meta: { label: 'Status' } }),
  ]);

  let globalFilter = $state('');
  let pagination = $state<PaginationState>({ pageIndex: 0, pageSize: 5 });
  let sorting = $state<SortingState>([]);

  // Stand-in for a server: filter, sort, then slice the requested page.
  const filtered = $derived.by(() => {
    const q = globalFilter.toLowerCase();
    let rows = q
      ? allData.filter((r) =>
          [r.name, r.email, r.role, r.status].some((v) => v.toLowerCase().includes(q)),
        )
      : allData;
    if (sorting.length > 0) {
      const { id, desc } = sorting[0];
      rows = [...rows].sort((a, b) => {
        const av = String(a[id as keyof User]);
        const bv = String(b[id as keyof User]);
        return desc ? bv.localeCompare(av) : av.localeCompare(bv);
      });
    }
    return rows;
  });

  const pageData = $derived(
    filtered.slice(
      pagination.pageIndex * pagination.pageSize,
      (pagination.pageIndex + 1) * pagination.pageSize,
    ),
  );

  const onGlobalFilterChange = (v: string) => {
    globalFilter = v;
    pagination = { ...pagination, pageIndex: 0 };
  };
  const onPaginationChange = (v: Updater<PaginationState>) => {
    pagination = typeof v === 'function' ? v(pagination) : v;
  };
  const onSortingChange = (v: Updater<SortingState>) => {
    sorting = typeof v === 'function' ? v(sorting) : v;
  };
</script>

<div class="wrap">
  <DataTable
    {columns}
    data={pageData}
    total={filtered.length}
    {globalFilter}
    {onGlobalFilterChange}
    {pagination}
    {onPaginationChange}
    {sorting}
    {onSortingChange}
    searchPlaceholder="Search by name, email, role…"
  />
</div>

<style>
  .wrap { width: 100%; min-width: 0; }
</style>

Props

PropTypeDefaultDescription
columnsColumnDef[]–Column definitions created with `createCaColumnHelper`. Required.
dataTData[]–Row data. In simple mode pass all rows; in controlled mode pass the current page. Required.
totalnumberdata.lengthTotal row count after filtering, used to compute the page count. Ignored in simple mode.
globalFilterstringundefinedSearch value. Passing it switches the table to controlled mode.
onGlobalFilterChange(v: string) => voidundefinedCalled when the user types in the search box.
paginationPaginationStateundefinedControlled `{ pageIndex, pageSize }`.
onPaginationChange(v: Updater<PaginationState>) => voidundefinedCalled when the page or page size changes.
sortingSortingStateundefinedControlled sorting, `[{ id, desc }]`.
onSortingChange(v: Updater<SortingState>) => voidundefinedCalled when the user clicks a column header.
labels{ noResults?, noResultsSub?, clearSearch? }undefinedOverrides the strings of the no-results state.
searchPlaceholderstringundefinedPlaceholder of the search input.
isLoadingbooleanundefinedShows a loading indicator in the toolbar.
isExportingbooleanundefinedShows the export button as busy.
onExport() => voidundefinedEnables the export button in the toolbar.
onRowClick(row: TData) => voidundefinedCalled when a row is clicked.
hasActiveFiltersbooleanundefinedTreats the table as filtered, which suppresses the empty state.
emptyStateSnippetundefinedCustom content shown when there is no data and no active filter.
childrenSnippetundefinedFilter chips such as `DataTableFacetedFilter`, rendered in the toolbar.
classstring''Extra class names on the wrapper.

Building blocks

DataTable is assembled from the parts below, all exported from @codeatlasdev/ui/table. You rarely need them: use them standalone when you render your own <table> markup around a table instance made with createCaTable, for example a layout DataTable does not offer. Inside DataTable the toolbar, pagination and column toggle are already wired. Use DataTableColumnHeader as a column header to get a sortable header, and pass DataTableFacetedFilter as children of DataTable.

<script lang="ts">
  import { renderComponent } from "@tanstack/svelte-table";
  import { createCaColumnHelper, DataTableColumnHeader } from "@codeatlasdev/ui/table";
  type User = { name: string };

  const col = createCaColumnHelper<User>();
  const columns = col.columns([
    col.accessor("name", {
      header: ({ column }) =>
        renderComponent(DataTableColumnHeader<User, string>, { column, title: "Name" }),
      meta: { label: "Name" },
    }),
  ]);
</script>

createCaColumnHelper, createCaTable, caTableFeatures and the CaColumn, CaColumnDef, CaColumnMeta, CaTable and CaTableFeatures types are exported from the same entry point. meta.label is the name shown in the column visibility menu.

DataTableToolbar props

PropTypeDefaultDescription
tableCaTable<TData>–Table instance from `createCaTable`. Required.
totalnumber–Result count shown in the toolbar. Required.
globalFilterstring–Current search value. Required.
onGlobalFilterChange(v: string) => void–Called when the user types in the search box. Required.
searchPlaceholderstringundefinedPlaceholder and accessible name of the search input.
isLoadingbooleanundefinedShows a spinner.
isExportingbooleanundefinedDisables the export button and shows a spinner in it.
onExport() => voidundefinedRenders the export button. It is disabled while `total` is 0.
childrenSnippetundefinedFilter controls rendered next to the search box.

The toolbar always includes DataTableColumnToggle on its right side.

DataTablePagination props

PropTypeDefaultDescription
tableCaTable<TData>–Table instance from `createCaTable`. Required.
totalnumber–Total row count shown next to the page indicator. Required.

It renders a page size select (10, 20, 50 or 100 rows), a page / pages indicator and previous and next buttons.

DataTableColumnHeader props

PropTypeDefaultDescription
columnCaColumn<TData, TValue>–Column the header belongs to. Required.
titlestring–Header text. Required.
classstring''Extra class names.

A sortable column renders a button that toggles sorting and shows the direction icon. A column that cannot sort renders the plain title.

DataTableColumnToggle props

PropTypeDefaultDescription
tableCaTable<TData>–Table instance from `createCaTable`. Required.

A menu of checkboxes, one per column that can be hidden. It follows the menu keyboard pattern: arrow keys move, Space and Enter toggle, Escape closes.

DataTableFacetedFilter props

PropTypeDefaultDescription
titlestring–Label of the filter button. Required.
facetsRecord<string, number>{}Option key to result count. Options are sorted by count, highest first.
labelMapRecord<string, string>{}Maps option keys to display labels.
selectedstring[][]Selected option keys.
onSelectionChange(values: string[]) => void–Called with the new selection. Required.