createDataTable API

Composable data table built on v0 primitives. Composes sorting, filtering, pagination, selection, and expansion into a single pipeline.

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