createDataTable API

API reference for the createDataTable composable.

Explore these related pages for additional context and usage patterns.

Page	Category
createDataTable	Data
createFilter	Data
createPagination	Data
createVirtual	Data

Functions

createDataTable

(options?: DataTableOptions<T>) => DataTableContext<T>

Creates a data table instance with sort controls, selection, and an adapter-driven data pipeline. Rows and columns are both managed via internal registries. Use `table.columns.register({ id, ... })` / `table.columns.onboard([...])` to add columns and `table.register({ id, value })` / `table.onboard([...])` for rows. Removing entries from the column registry reactively updates `leaves`, `headers`, the sort group, and the filter pipeline. Must be called inside a component `setup()` or a Vue effect scope. Calling at module scope in SSR environments causes request state leakage.

createDataTableContext

(_options?: DataTableContextOptions<T>) => ContextTrinity<DataTableContext<T>>

Creates a data table context with dependency injection support. The returned context exposes both row and column registries. Columns must be onboarded after construction — pass them via `context.columns.onboard`, not in the factory options.

useDataTable

(namespace?: string) => DataTableContext<T>

Returns the current data table context from dependency injection.

computeDepth

typeof computeDepth

extractLeaves

typeof extractLeaves

resolveHeaders

typeof resolveHeaders

Options

filter

Omit<FilterOptions, "keys"> | undefined

Filter options (keys derived from columns)

pagination

Omit<PaginationOptions, "size"> | undefined

Pagination options (size derived from pipeline)

sortMultiple

boolean | undefined

Enable multi-column sort.

Default: false

mandate

boolean | undefined

Prevent clearing sort (asc → desc → asc cycle).

Default: false

firstSortOrder

"asc" | "desc" | undefined

Direction for first sort click.

Default: 'asc'

selectStrategy

SelectStrategy | undefined

Selection strategy: 'single' selects one row, 'page' operates on visible items, 'all' operates on all filtered items.

Default: 'page'

itemSelectable

(keyof T & string) | undefined

Property that controls per-row selectability

groupBy

(keyof T & string) | undefined

Column id to group rows by

openAll

boolean | undefined

Auto-open all groups on creation.

Default: false

expandMultiple

boolean | undefined

Allow multiple rows expanded simultaneously.

Default: true

locale

string | undefined

Locale for sorting (defaults to useLocale's selected locale or browser default)

adapter

DataTableAdapter<T> | undefined

Pipeline adapter.

Default: ClientDataTableAdapter

Properties

collection

ReadonlyMap<ID, E>

The collection of tickets in the registry

size

number

The number of tickets in the registry

items

Readonly<Ref<readonly T[], readonly T[]>>

Final paginated items for rendering

allItems

Readonly<Ref<readonly T[], readonly T[]>>

Raw unprocessed items

filteredItems

Readonly<Ref<readonly T[], readonly T[]>>

Items after filtering

sortedItems

Readonly<Ref<readonly T[], readonly T[]>>

Items after filtering and sorting

columns

RegistryContext<DataTableColumnTicketInput<T>, DataTableColumnTicket<T>>

Column registry. Use `columns.register({...})`, `columns.onboard([...])`, `columns.unregister(id)`, and `columns.clear()` to manage columns. The registry is reactive — `leaves` and `headers` recompute when it mutates.

leaves

Readonly<Ref<readonly DataTableColumnTicket<T>[], readonly DataTableColumnTicket<T>[]>>

Leaf columns (no children) used by the data pipeline. Reactive.

headers

Readonly<Ref<InternalHeader[][], InternalHeader[][]>>

2D header grid with colspan/rowspan for rendering thead. Reactive.

query

Readonly<ShallowRef<string>>

Current search query (readonly)

sort

DataTableSort

Sort controls

pagination

PaginationContext

Pagination controls

selection

DataTableSelection

Row selection controls

expansion

DataTableExpansion

Row expansion controls

grouping

DataTableGrouping<T>

Row grouping controls. When groupBy is not set, `groups` returns an empty array.

total

Readonly<Ref<number, number>>

Total row count for aria-rowcount

loading

Readonly<Ref<boolean, boolean>>

Loading state (managed by adapter)

error

Readonly<Ref<Error | null, Error | null>>

Error state (managed by adapter)

Methods

clear

() => void

Clear the entire registry

has

(id: ID) => boolean

Check if a ticket exists by ID

keys

() => readonly ID[]

Get all registered IDs

browse

(value: E["value"]) => readonly ID[] | undefined

Browse for an ID(s) by value

lookup

(index: number) => ID | undefined

Lookup a ticket by index number

get

(id: ID) => E | undefined

Get a ticket by ID

upsert

(id: ID, ticket?: Partial<Z>, event?: string) => E

Update or insert a ticket by ID

values

() => readonly E[]

Get all values of registered tickets

entries

() => readonly [ID, E][]

Get all entries of registered tickets

register

(ticket?: Partial<Z & RegistryTicket>) => E

unregister

(id: ID) => void

Unregister a ticket by ID

reindex

() => void

Reset the index directory and update all tickets

move

(id: ID, toIndex: number) => E | undefined

Move a ticket to a new index position

reorder

(ids: ID[]) => void

Reorder the registry to match a canonical permutation of ids in one pass.

seek

(direction?: "first" | "last", from?: number, predicate?: (ticket) => boolean) => E | undefined

Seek for a ticket based on direction and optional predicate

on

<K extends Extensible<RegistryEventName>>(event: K, cb: RegistryEventCallback<E, K>) => void

Listen for registry events

off

<K extends Extensible<RegistryEventName>>(event: K, cb: RegistryEventCallback<E, K>) => void

Stop listening for registry events

emit

<K extends Extensible<RegistryEventName>>(event: K, data: EventPayload<E, K>) => void

Emit an event with data

dispose

() => void

Clears the registry and removes all listeners

onboard

(registrations: Partial<Z & RegistryTicket>[]) => E[]

Onboard multiple tickets at once

offboard

(ids: ID[]) => Partial<Z>[]

Offboard multiple tickets at once, returning the input shapes that were removed.

batch

<R>(fn: () => R) => R

Execute operations in a batch, deferring cache invalidation and event emission until complete

search

(value: string) => void

Set the search query