createDataGrid API

API reference for the createDataGrid composable.

Explore these related pages for additional context and usage patterns.

Page	Category
createDataGrid	Data
createDataTable	Data
createFilter	Data
createPagination	Data
createVirtual	Data

Functions

createDataGrid

(_options?: DataGridOptions<T>) => DataGridContext<T>

Creates a data grid instance with layout, editing, row ordering, and spanning layered on top of the createDataTable pipeline. Rows live on the inherited registry surface — register them with `grid.onboard(rows.map(value => ({ id: value.id, value })))` or `grid.register({ id, value })`.

createDataGridContext

(_options?: DataGridContextOptions<T>) => ContextTrinity<DataGridContext<T>>

Creates a data grid context with dependency injection support.

useDataGrid

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

Returns the current data grid context from dependency injection.

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

editing

{ onEdit?: (row: ID, column: string, value: unknown, item: T) => void; } | undefined

preserveRowOrder

MaybeRefOrGetter<boolean> | undefined

rowSpanning

((item: T, column: string) => number) | undefined

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)

layout

ColumnLayout

editing

CellEditing

spans

ComputedRef<Map<ID, Map<string, SpanEntry>>>

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

rows

{ order: Readonly<Ref<ID[]>>; move: (id: ID, toIndex: number) => void; reset: () => void; }