Data Table

DataTable renders typed columns and row data as a semantic HTML table. Akaza manages structure and interaction state. Your application supplies data, cell content, and styles.

It supports sorting, filtering, selection, pagination, grouped headers, expandable rows, and pinned columns. It renders a native table and keeps standard table reading behavior for screen readers.

Anatomy

• #toolbar: Search, filters, view controls, and bulk actions above the table.
• #caption: Visible or visually hidden table caption.
• #[column.id]-header: Header content for one column.
• #header: Generic fallback for every header.
• #sort-indicator: Sort direction indicator.
• #[column.id]-cell: Cell content for one column, such as #name-cell.
• #cell: Generic fallback for every body cell.
• #expanded: Detail row rendered after an expanded data row.
• #[column.id]-footer: Footer content for one column.
• #footer: Generic fallback for every footer cell.
• #pagination: Replaces the built-in Pagination composition.
• #loading, #error, #empty: Complete table-body states.
• #expansion-trigger, #reorder-handle, #column-reorder-handle, #resize-handle: Interaction control content.

Data Table generates the native table structure, controls, state rows, paginator, and result count. Generic #header and #cell slots keep built-in controls. A column slot replaces that part, including any selection, sorting, expansion, or reorder control it contained.

Usage

<script setup lang="ts">
import type { DataTableColumn, DataTableRowKey } from "akaza-ui";
import { DataTable } from "akaza-ui";
import { ref } from "vue";

interface User {
  id: number;
  name: string;
  email: string;
  status: "active" | "invited";
}

const rows: User[] = [
  { id: 1, name: "Ada Lovelace", email: "ada@example.com", status: "active" },
  { id: 2, name: "Grace Hopper", email: "grace@example.com", status: "invited" },
];

const columns: DataTableColumn<User>[] = [
  { id: "select", type: "selection", size: 44 },
  { accessor: "name", header: "Member", sortable: true },
  { accessor: "status", header: "Status", sortable: true },
  { id: "actions", type: "display", header: "" },
];

const selection = ref<DataTableRowKey[]>([]);
</script>

<template>
  <DataTable
    v-model:selection="selection"
    :data="rows"
    :columns="columns"
    row-key="id"
    selection-mode="multiple"
  >
    <template #name-cell="{ row }">
      <strong>{{ row.original.name }}</strong>
      <small>{{ row.original.email }}</small>
    </template>

    <template #actions-cell="{ row }">
      <button type="button" @click.stop="openUser(row.original)">Open</button>
    </template>
  </DataTable>
</template>

Examples

Custom headers and cells

Use #[id]-header and #[id]-cell for the clearest template-first API. Each cell receives the row, column, resolved value, indexes, and table controller.

<DataTable :data="users" :columns="columns" row-key="id">
  <template #name-header="{ column, toggleSorting }">
    <button type="button" @click="toggleSorting">{{ column.definition.header }}</button>
  </template>

  <template #name-cell="{ row }">
    <Avatar :src="row.original.avatar" />
    <span>{{ row.original.firstName }} {{ row.original.lastName }}</span>
  </template>

  <template #status-cell="{ value }">
    <StatusBadge :status="value" />
  </template>
</DataTable>

Column render functions are also supported when definitions belong in TypeScript. Slot precedence is specific named slot, generic slot, column render function, then formatted accessor value. Use createDataTableColumnHelper<T>() when a render function needs its accessor value inferred instead of unknown.

import { createDataTableColumnHelper } from "akaza-ui";

const column = createDataTableColumnHelper<User>();

const columns = [
  column.accessor("name", {
    header: ({ column }) => h("span", { class: "min-w-48" }, column.id),
    cell: ({ row }) => h(UserSummary, { user: row.original }),
    ui: { header: "min-w-48", cell: "font-medium" },
    attrs: { cell: ({ row }) => ({ "data-user-id": row.id }) },
  }),
];

Sorting and filtering

Sorting and filters are Vue models. Use controller methods in the toolbar so all changes use the same cancelable event path.

<DataTable
  v-model:sorting="sorting"
  v-model:filters="filters"
  v-model:global-filter="search"
  :data="users"
  :columns="columns"
  row-key="id"
  sorting-mode="multiple"
>
  <template #toolbar="{ table }">
    <input
      :value="search"
      type="search"
      @input="table.setGlobalFilter($event.target.value, $event)"
    >
    <button type="button" @click="table.setFilter('status', 'active', $event)">
      Active only
    </button>
    <button type="button" @click="table.clearFilter('status', $event)">
      All statuses
    </button>
  </template>
</DataTable>

Hold Shift, Control, or Command while activating headers to retain existing sorts in multiple mode.

undefined clears a column filter; null, false, 0, and "" remain available to custom filter functions. The default case-insensitive text matcher treats empty values as no filter. Prefer clearFilter(id) when intent should be explicit. An accepted filter or sort change resets pagination to page 1 as one transaction. Canceling either paired change event cancels the whole transaction.

Selection and bulk actions

Add a selection column and choose single or multiple. Selection stores stable rowKey values, so sorting and filtering never attach state to the wrong row.

<DataTable
  v-model:selection="selectedIds"
  :data="users"
  :columns="columns"
  row-key="id"
  selection-mode="multiple"
  selection-behavior="row"
  :is-row-selectable="row => !row.locked"
  select-all-scope="filtered"
>
  <template #toolbar="{ table }">
    <button :disabled="!table.selectedRows.value.length" @click="archive(selectedIds)">
      Archive selected
    </button>
  </template>
</DataTable>

selectionBehavior="control" changes selection only through checkboxes or radios. "row" also selects from non-interactive row space; links, buttons, inputs, and editable controls remain independent.

Disabled rows render disabled native selection controls. In manual pagination, selectedRows can resolve only keys present in the currently supplied page; keep bulk selection data in application state when selections span server pages.

Pagination

Set paginate for client pagination. The bundled paginator is styled through the pagination* UI keys or replaced through #pagination.

<DataTable
  v-model:pagination="pagination"
  :data="users"
  :columns="columns"
  row-key="id"
  paginate
>
  <template #pagination="{ page, pageCount, setPage }">
    <button :disabled="page === 1" @click="setPage(page - 1)">Previous</button>
    <span>Page {{ page }} of {{ pageCount }}</span>
    <button :disabled="page === pageCount" @click="setPage(page + 1)">Next</button>
  </template>
</DataTable>

When filtering or a smaller data set removes the current page, DataTable clamps v-model:pagination to the last available page. page and pageSize accept finite numbers only.

Server-controlled data

Enable manual modes when supplied data is already processed by an API. Akaza updates models but does not sort, filter, or slice rows again. Change events fire before model commits so details.cancel() can reject a change; do not fetch from those events. Observe committed Vue state instead, and cancel stale requests.

<script setup lang="ts">
const sorting = ref([]);
const filters = ref({});
const pagination = ref({ page: 1, pageSize: 25 });
const query = computed(() => ({
  sorting: sorting.value,
  filters: filters.value,
  pagination: pagination.value,
}));

watch(query, async (value, _previous, onCleanup) => {
  const request = new AbortController();
  onCleanup(() => request.abort());
  response.value = await fetchRows(value, request.signal);
}, { immediate: true });
</script>

<template>
  <DataTable
  v-model:sorting="sorting"
  v-model:filters="filters"
  v-model:pagination="pagination"
  :data="response.rows"
  :columns="columns"
  :row-count="response.total"
  row-key="id"
  manual-sorting
  manual-filtering
  manual-pagination
  />
</template>

rowCount is the total server result count, not current page length. selectAllScope="filtered", filteredRowCount, and client-side selected-row resolution cover loaded rows only in manual modes. Use globally stable rowKey values across every page.

Grouped headers and details

Nested column definitions generate proper colspan, rowspan, and scope values. An expander column controls detail rows.

const columns = [
  { id: "expand", type: "expander", header: "" },
  {
    id: "identity",
    header: "Identity",
    children: [
      { accessor: "name", header: "Name" },
      { accessor: "email", header: "Email" },
    ],
  },
];

<DataTable
  v-model:expanded="expandedIds"
  :data="users"
  :columns="columns"
  row-key="id"
  :is-row-expandable="row => Boolean(row.auditLog.length)"
>
  <template #expanded="{ row }">
    <AuditLog :entries="row.original.auditLog" />
  </template>
</DataTable>

Use getSubRows instead when data is hierarchical and child records should become ordinary nested table rows.

Set rowHeader: true on the identifying column to render its body cells as native <th scope="row"> elements.

Column layout

Sizing, order, visibility, and pinning use separate models. Pointer and keyboard input update those models.

<DataTable
  v-model:column-sizing="columnSizing"
  v-model:column-order="columnOrder"
  v-model:column-visibility="columnVisibility"
  v-model:column-pinning="columnPinning"
  :data="users"
  :columns="columns"
  row-key="id"
  sticky-header
  column-reorder
  :column-resize="{ behavior: 'fit', update: 'change', keyboardStep: 12 }"
>
  <template #toolbar="{ table }">
    <button @click="table.setColumnVisible('email', false, $event)">Hide email</button>
    <button @click="table.setColumnPinned('name', 'start', $event)">Pin name</button>
  </template>
</DataTable>

Column sizes use pixels and a fixed table layout. expand changes total table width. fit transfers width to an adjacent column. Pinned headers sit above pinned body and footer cells. Consumer min-width and width rules can override calculated sizes.

Row reorder is available only for flat, unsorted rows. Sorting or hierarchical depth disables native reorder buttons and controller moves, avoiding ambiguous source order. Filtered and paginated moves still operate on stable row keys in the full supplied array.

Loading, error, and empty states

State rows preserve the table structure and span every visible column. Replace their content without rebuilding the table.

<DataTable :data="rows" :columns="columns" row-key="id" :loading="pending" :error="error">
  <template #loading>Loading members...</template>
  <template #error="{ error }">{{ getMessage(error) }}</template>
  <template #empty>No members match these filters.</template>
</DataTable>

API Reference

Models

Props

Column Shape

Emits

Every model emits its update:* event after an accepted change. The paired *-change event fires first with (value, details); details.cancel() prevents the model update.

Slots

Controller

#toolbar, cell/header contexts, #pagination, useDataTable(), and the exposed table property use the same Vue-native controller.

The component instance exposes getColumn, getRow, setFilter, clearFilter, setGlobalFilter, setPage, setPageSize, and reset.

UI Options

Styling Hooks

Plain class applies to the outer root. Use ui.table, section keys, or per-column ui and attrs for granular control. DataTable ships only behavior-critical layout for overflow, sizing, sticky/pinned positioning, resize targets, and the live region.

Keyboard

Pointer dragging and touch Pointer Events use the same resize and reorder actions. The table does not add spreadsheet-style arrow navigation to ordinary data cells; native table reading and normal document tab order remain intact.