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. 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.

useDataTable

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

Returns the current data table context from dependency injection.

Options

items required

MaybeRefOrGetter<T[]>

Source items

columns required

readonly DataTableColumn<T>[]

Column definitions

itemValue

KeysOfType<T, ID> | undefined

Property used as row identifier. Must resolve to a string or number value.

Default: 'id'

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 key to group rows by

enroll

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

DataTableAdapterInterface<T> | undefined

Pipeline adapter.

Default: ClientAdapter

Properties

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

readonly DataTableColumn<T>[]

Column definitions

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

search

(value: string) => void

Set the search query