Headless engine API reference

API reference

Every public export of @pretable/core: createGrid, the PretableGrid handle, and the supporting types.

The complete public surface of @pretable/core.

`createGrid`

function createGrid<TRow extends PretableRow = PretableRow>(
  options: PretableGridOptions<TRow>,
): PretableGrid<TRow>;

Creates an engine instance. TRow defaults to PretableRow (Record<string, unknown>); pass your row type for typed accessors.

`PretableGridOptions<TRow>`

Field	Type	Notes
`columns`	`PretableColumn<TRow>[]`	Column definitions.
`rows`	`TRow[]`	The source rows.
`getRowId`	`(row: TRow, index: number) => string`	Optional. How to derive a stable id for each row.
`autosize`	`boolean \| AutosizeOptions`	Optional. Autosize columns to content on creation.

`PretableGrid<TRow>`

The handle returned by createGrid. It carries two readonly fields and the store + mutation methods.

readonly kind: "pretable-grid";
readonly options: PretableGridOptions<TRow>;

Store

Method	Signature	Notes
`getSnapshot`	`() => PretableGridSnapshot<TRow>`	Current state; identity stable until the next mutation.
`subscribe`	`(listener: () => void) => () => void`	Registers a listener; returns an unsubscribe fn.

Sort & filter

Method	Signature
`setSort`	`(columnId: string \| null, direction: PretableSortDirection) => void`
`setColumnFilter`	`(columnId: string, filter: ColumnFilter \| null) => void`
`replaceFilters`	`(nextFilters: Record<string, ColumnFilter>) => void`
`clearFilters`	`() => void`
`distinctColumnValues`	`(columnId: string) => string[]`

Selection & ranges

Method	Signature
`toggleRowSelection`	`(rowId: string) => void`
`selectAll`	`() => void`
`clearSelection`	`() => void`
`setSelection`	`(state: PretableSelectionState) => void`
`setSelectAllVisible`	`(checked: boolean) => void`
`addRange`	`(range: PretableCellRange) => void`
`extendRangeFromAnchor`	`(addr: PretableCellAddress) => void`

Focus & movement

Method	Signature
`setFocus`	`(addr: PretableCellAddress \| null) => void`
`moveFocus`	`(direction: PretableFocusDirection, options?: PretableMoveFocusOptions) => void`

Column layout

Method	Signature
`setColumnWidth`	`(columnId: string, width: number) => void`
`setColumnPinned`	`(columnId: string, pinned: "left" \| null) => void`
`moveColumn`	`(columnId: string, toIndex: number) => void`
`autosizeColumn`	`(columnId: string, options?: AutosizeOptions) => void`
`autosizeColumns`	`(options?: AutosizeOptions) => void`
`resetColumnLayout`	`() => void`
`mergeColumnsFromProps`	`(nextColumns: PretableColumn<TRow>[]) => void`

Data & viewport

Method	Signature
`applyTransaction`	`(transaction: PretableTransaction<TRow>) => void`
`setViewport`	`(viewport: PretableViewportState) => void`

Types

`PretableColumn<TRow>`

interface PretableColumn<TRow = PretableRow> {
  id: string;
  header?: string;
  value?: (row: TRow) => unknown;
  format?: (input: PretableFormatInput<TRow>) => string;
  sortable?: boolean;
  filterable?: boolean;
  filterType?: FilterType;
  filterOptions?: FilterOption[];
  reorderable?: boolean;
  resizable?: boolean;
  pinned?: "left";
  wrap?: boolean;
  widthPx?: number;
  minWidthPx?: number;
  maxWidthPx?: number;
}

Filter types

type FilterType = "text" | "number" | "date" | "enum";
 
type FilterOperator =
  | "contains"
  | "notContains"
  | "equals"
  | "notEquals"
  | "startsWith"
  | "endsWith"
  | "gt"
  | "gte"
  | "lt"
  | "lte"
  | "between"
  | "isAnyOf"
  | "isNoneOf"
  | "on"
  | "before"
  | "after"
  | "dateBetween"
  | "isEmpty"
  | "isNotEmpty";
 
type FilterValue =
  | string
  | number
  | readonly [number, number]
  | readonly [string, string]
  | readonly string[]
  | null;
 
interface ColumnFilter {
  operator: FilterOperator;
  value?: FilterValue;
}
 
interface FilterOption {
  value: string;
  label?: string;
}

Each column's filterType (default "text") selects which operators apply and how values are compared. Columns are AND-combined. filterOptions supplies the choices for an enum column; when omitted, call distinctColumnValues(columnId) to derive them from the data.

`PretableRow`

type PretableRow = Record<string, unknown>;

`PretableGridSnapshot<TRow>`

interface PretableGridSnapshot<TRow = PretableRow> {
  visibleRows: PretableVisibleRow<TRow>[];
  visibleRange: PretableRowRange;
  totalRowCount: number;
  sort: PretableSortState;
  filters: Record<string, ColumnFilter>;
  selection: PretableSelectionState;
  focus: PretableFocusState;
  viewport: PretableViewportState;
}

See Snapshot & subscribe for what each field means.

`PretableVisibleRow<TRow>`

interface PretableVisibleRow<TRow = PretableRow> {
  id: string;
  row: TRow;
  sourceIndex: number;
}

`PretableRowRange`

interface PretableRowRange {
  start: number;
  end: number;
}

`PretableSortState` / `PretableSortDirection`

type PretableSortDirection = "asc" | "desc" | null;
 
interface PretableSortState {
  columnId: string | null;
  direction: PretableSortDirection;
}

`PretableSelectionState`

interface PretableSelectionState {
  anchor: PretableCellAddress | null;
  ranges: PretableCellRange[];
}

`PretableCellRange` / `PretableCellAddress`

interface PretableCellRange {
  startRowId: string;
  endRowId: string;
  startColumnId: string;
  endColumnId: string;
}
 
interface PretableCellAddress {
  rowId: string;
  columnId: string;
}

`PretableFocusState` / `PretableFocusDirection`

type PretableFocusDirection = "up" | "down" | "left" | "right";
 
interface PretableFocusState {
  rowId: string | null;
  columnId: string | null;
}

`PretableMoveFocusOptions`

interface PretableMoveFocusOptions {
  byPage?: boolean;
  extend?: boolean;
  jumpToEdge?: boolean;
}

`PretableViewportState`

interface PretableViewportState {
  scrollTop: number;
  scrollLeft: number;
  width: number;
  height: number;
}

`PretableTransaction<TRow>`

interface PretableTransaction<TRow = PretableRow> {
  add?: TRow[];
  update?: Partial<TRow>[];
  remove?: string[];
}

`PretableFormatInput<TRow>`

interface PretableFormatInput<TRow = PretableRow> {
  value: unknown;
  row: TRow;
  column: PretableColumn<TRow>;
}

`AutosizeOptions`

interface AutosizeOptions {
  minWidthPx?: number;
  maxWidthPx?: number;
  cellPaddingPx?: number;
  averageCharWidth?: number;
}

`PretableRowSelectionTriState`

type PretableRowSelectionTriState = "selected" | "indeterminate";

The state a "select all" control reflects when the current selection is a partial set of rows — useful when you render your own header checkbox alongside selectAll() / setSelectAllVisible().

createGrid

PretableGridOptions<TRow>

PretableGrid<TRow>

Store

Sort & filter

Selection & ranges

Focus & movement

Column layout

Data & viewport

Types

PretableColumn<TRow>

Filter types

PretableRow

PretableGridSnapshot<TRow>

PretableVisibleRow<TRow>

PretableRowRange

PretableSortState / PretableSortDirection

PretableSelectionState

PretableCellRange / PretableCellAddress

PretableFocusState / PretableFocusDirection

PretableMoveFocusOptions

PretableViewportState

PretableTransaction<TRow>

PretableFormatInput<TRow>

AutosizeOptions

PretableRowSelectionTriState

See also