Data Table
Display records with sorting, filtering, selection, and pagination.
Demos
Usage
<script setup lang="ts">
import { Accordion } from '~/components/ui/accordion'
const items = [
{ value: 'source', label: 'Do I own the source?', content: 'Yes. Copy and adapt the files.' },
]
</script>
<template>
<Accordion :items="items" />
</template>
Sorting and selection
Click a column heading to sort. Add a selection column and bind selection to stable row keys. Selection remains independent of sorting and pagination.
0 selected
<AppLayout :viewport="false" scroll="page">
<template #header>Workspace</template>
<template #left><ProjectNavigation /></template>
<ProjectList />
<template #footer>2 projects</template>
</AppLayout>
Filtering and pagination
Bind globalFilter to your search input. Enable paginate and bind the one-based page and page size. For server data, use the manual filtering and pagination props instead.
<AppLayout :layout="{ header: 'full', footer: 'content' }">
<template #left><ProjectNavigation /></template>
<ProjectList />
<template #right><ProjectDetails /></template>
</AppLayout>
Expanded details
Add an expander column and isRowExpandable for rows with detail content. Use the expanded slot to render those details.
@layer akaza-reset;
@import '@fontsource/inter/latin-400.css';
@import '@fontsource/inter/latin-500.css';
@import '@fontsource/inter/latin-600.css';
@import '@fontsource/jetbrains-mono/latin-400.css';
@import 'tailwindcss';
@import 'akaza-ui/dist/akaza-ui.css';
Empty, loading, and error states
Use the state picker to inspect each result. Supply an actionable error message when loading fails; distinguish it from an empty result.
<DataTable :data="projects" :columns="columns" row-key="id" :loading="pending" :error="error" />
Installation
Complete the shared installation. Copy DataTable.vue and index.ts into app/components/ui/data-table/. Also copy the required components: Pagination.
<script setup lang="ts" generic="T extends object">
import { DataTable as Primitive } from 'akaza-ui'
import type * as Akaza from 'akaza-ui'
import { computed, useAttrs, useTemplateRef } from 'vue'
import { cn } from '../../../utils/ui'
import { Pagination } from '../pagination'
import uiConfig from '../ui.config'
import {
dataTableVariants,
resolveDataTableVariants,
type DataTableProps,
type DataTableSlots,
} from './index'
defineOptions({ inheritAttrs: false })
// Preserve Akaza defaults when optional props, including Boolean aliases, are omitted.
const props = withDefaults(defineProps<DataTableProps<T>>(), {
caption: undefined,
ariaLabel: undefined,
ariaLabelledby: undefined,
ariaDescribedby: undefined,
loading: undefined,
error: undefined,
emptyLabel: undefined,
errorLabel: undefined,
sortingMode: undefined,
manualSorting: undefined,
manualFiltering: undefined,
paginate: undefined,
manualPagination: undefined,
rowCount: undefined,
showPagination: undefined,
selectionMode: undefined,
selectionBehavior: undefined,
selectAllScope: undefined,
isRowSelectable: undefined,
isRowExpandable: undefined,
getSubRows: undefined,
columnResize: undefined,
columnReorder: undefined,
rowReorder: undefined,
stickyHeader: undefined,
dir: undefined,
labels: undefined,
rowAttrs: undefined,
ui: undefined,
selection: undefined,
sorting: undefined,
filters: undefined,
globalFilter: undefined,
pagination: undefined,
expanded: undefined,
columnVisibility: undefined,
columnOrder: undefined,
columnSizing: undefined,
columnPinning: undefined,
rowOrder: undefined,
})
defineSlots<DataTableSlots<T>>()
const attrs = useAttrs()
const resolved = computed(() => resolveDataTableVariants(props, uiConfig))
const styles = computed(() => dataTableVariants(resolved.value))
const mergedUi = computed(() => {
const overrides = props.ui as Record<string, string | undefined> | undefined
return Object.fromEntries(
Object.entries(styles.value).map(([part, style]) => [
part,
cn(style(), overrides?.[part], part === 'root' ? props.class : undefined),
]),
)
})
const paginationUi = computed(() =>
Object.fromEntries(
['root', 'list', 'item', 'first', 'previous', 'page', 'ellipsis', 'next', 'last'].map(
(part) => [part, mergedUi.value[`pagination${part[0]!.toUpperCase()}${part.slice(1)}`]],
),
),
)
function setPaginationPage(
setPage: (page: number, event?: Event) => boolean,
page: number,
details: Akaza.AkazaChangeEventDetails,
) {
details.cancel()
setPage(page, details.event)
}
const primitiveProps = computed(() => {
const { class: _class, ui: _ui, size: _size, ...native } = props
return native
})
const primitive = useTemplateRef<
{ table: Akaza.DataTableController<T> } & Pick<
Akaza.DataTableController<T>,
| 'getColumn'
| 'getRow'
| 'reset'
| 'clearFilter'
| 'setFilter'
| 'setGlobalFilter'
| 'setPage'
| 'setPageSize'
>
>('primitive')
defineExpose({
get table() {
return primitive.value!.table
},
get getColumn() {
return primitive.value!.getColumn
},
get getRow() {
return primitive.value!.getRow
},
get reset() {
return primitive.value!.reset
},
get clearFilter() {
return primitive.value!.clearFilter
},
get setFilter() {
return primitive.value!.setFilter
},
get setGlobalFilter() {
return primitive.value!.setGlobalFilter
},
get setPage() {
return primitive.value!.setPage
},
get setPageSize() {
return primitive.value!.setPageSize
},
})
</script>
<template>
<component
:is="Primitive"
ref="primitive"
v-bind="{ ...primitiveProps, ...attrs }"
:ui="mergedUi"
>
<template v-if="!$slots.pagination" #pagination="scope">
<Pagination
:model-value="scope.page"
:total="manualPagination ? (rowCount ?? data.length) : scope.table.filteredRowCount.value"
:items-per-page="scope.pageSize"
:size="resolved.size ?? 'md'"
:show-edges="true"
:ui="paginationUi"
@value-change="
(page: number, details: Akaza.AkazaChangeEventDetails) =>
setPaginationPage(scope.setPage, page, details)
"
/>
</template>
<template v-for="(_, name) in $slots" #[name]="scope"
><slot :name="name as keyof DataTableSlots<T>" v-bind="scope ?? {}"
/></template>
</component>
</template>
API
Variants and defaults
| Prop | Values | Default |
|---|---|---|
size | xs, sm, md, lg, xl | md |
Models
| Model | Type | Default | Description |
|---|---|---|---|
v-model:selection | rowKey | rowKey[] | null | null | Selected stable row keys. |
v-model:sorting | DataTableSorting[] | [] | Ordered sort descriptors. |
v-model:filters | Record<string, unknown> | {} | Per-column filter values. |
v-model:globalFilter | string | "" | Global search text. |
v-model:pagination | { page, pageSize } | { page: 1, pageSize: 10 } | One-based page state. |
v-model:expanded | rowKey[] | [] | Expanded row keys. |
v-model:columnVisibility | Record<string, boolean> | {} | Column visibility overrides. |
v-model:columnOrder | string[] | [] | Leaf column order. |
v-model:columnSizing | Record<string, number> | {} | Column widths in pixels. |
v-model:columnPinning | { start: string[], end: string[] } | empty sides | Pinned leaf columns. |
v-model:rowOrder | rowKey[] | [] | User-controlled row order. |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
data | readonly T[] | required | Rows supplied to the table. |
columns | readonly DataTableColumn<T>[] | required | Typed column definitions. |
rowKey | keyof T | (row, index) => string | number | required | Stable row identity. |
caption | string | — | Native table caption text. |
ariaLabel | string | — | Accessible table label when no caption is used. |
ariaLabelledby | string | — | ID of an external table label. |
ariaDescribedby | string | — | IDs describing the table. |
loading | boolean | false | Renders loading state and aria-busy. |
error | boolean | string | Error | false | Renders error state. |
emptyLabel | string | "No results." | Default empty-state text. |
errorLabel | string | "Unable to load results." | Default non-Error message. |
sortingMode | "single" | "multiple" | "single" | Number of retained sort descriptors. |
manualSorting | boolean | false | Disables client sorting. |
manualFiltering | boolean | false | Disables client filtering. |
paginate | boolean | false | Enables client pagination. |
manualPagination | boolean | false | Treats supplied data as an API page. |
rowCount | number | — | Total server row count for manual pagination. |
showPagination | boolean | true | Shows built-in or slotted pagination. |
selectionMode | "none" | "single" | "multiple" | "none" | Selection behavior. |
selectionBehavior | "control" | "row" | "control" | Whether non-interactive row clicks select. |
selectAllScope | "page" | "filtered" | "page" | Rows affected by select all. |
isRowSelectable | (row) => boolean | all rows | Disables selection per row. |
isRowExpandable | (row) => boolean | rows with children | Enables detail expansion per row. |
getSubRows | (row) => readonly T[] | — | Returns hierarchical child rows. |
columnResize | boolean | DataTableColumnResizeOptions | false | Enables pointer/touch/keyboard resizing. |
columnReorder | boolean | false | Enables pointer/touch/keyboard column reorder handles. |
rowReorder | boolean | false | Enables pointer/touch/keyboard row reorder handles. |
stickyHeader | boolean | false | Keeps headers at the viewport top. |
dir | "ltr" | "rtl" | "ltr" | Logical direction for sizing and pinning. |
labels | DataTableLabels | English labels | Accessible control and state labels. |
rowAttrs | HTMLAttributes | (row) => HTMLAttributes | — | Native attributes/classes for every row. |
ui | DataTableUi | — | Classes for structural parts. |
Slots
| Slot | Props | Description |
|---|---|---|
toolbar | table | Controls above the viewport. |
caption | — | Native caption content. |
[column.id]-header | header context | Specific header renderer. |
header | header context | Generic header renderer. |
sort-indicator | column, sorted | Sort direction content. |
[column.id]-cell | cell context | Specific cell renderer. |
cell | cell context | Generic cell renderer. |
expanded | row, table | Detail row content. |
[column.id]-footer | column, table | Specific footer content. |
footer | column, table | Generic footer content. |
pagination | table, page, pageSize, pageCount, setPage, setPageSize | Replaces default paginator. |
loading | table | Loading row content. |
error | error, table | Error row content. |
empty | table | Empty row content. |
expansion-trigger | row | Expand/collapse control content. |
reorder-handle | row | Row drag handle content. |
column-reorder-handle | column | Column drag handle content. |
resize-handle | column | Resize handle content. |
Events
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.
| Event | Description |
|---|---|
selection-change | Selection changed. |
sorting-change | Sort descriptors changed. |
filters-change | Column filters changed. |
global-filter-change | Global filter changed. |
pagination-change | Page or page size changed. |
expanded-change | Expanded row keys changed. |
column-visibility-change | Visibility map changed. |
column-order-change | Leaf column order changed. |
column-sizing-change | Width map changed. |
column-pinning-change | Pin sides changed. |
row-order-change | Row order changed. |
reset-change | Atomic reset requested. Canceling it preserves every model. |
row-click | Native row click with row and cancelable details. |
row-contextmenu | Native row context-menu event with row details. |
cell-click | Native cell click with cell context and details. |
Keyboard
| Control | Key | Behavior |
|---|---|---|
| sort header | Enter / Space | Cycles sort direction through its native button. |
| selection control | Space | Selects a row or the configured select-all scope. |
| expansion control | Enter / Space | Opens or closes row details/children. |
| resize separator | ArrowLeft / ArrowRight | Changes width by keyboardStep, respecting RTL. |
| resize separator | Home | Restores the definition width or 150px. |
| column reorder handle | ArrowLeft / ArrowRight | Moves the column one visible position. |
| row reorder handle | ArrowUp / ArrowDown | Moves the row one visible position. |
| pagination | Tab, Enter, Space | Uses native Pagination button/link behavior. |
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.