TypeScript Types

The types/ directory contains all TypeScript type definitions and interfaces used throughout the data table components.

Source Code ↗

Core Types

Option

Option type for select/multi-select filters.

interface Option {
  label: string
  value: string
  count?: number
  icon?: React.ComponentType<{ className?: string }>
}

FilterVariant

Filter variant type defining the UI control type.

type FilterVariant =
  | "text"
  | "number"
  | "range"
  | "date"
  | "dateRange"
  | "select"
  | "multiSelect"
  | "boolean"

FilterOperator

Filter operator type defining the comparison logic.

type FilterOperator =
  | "ilike"
  | "not.ilike"
  | "eq"
  | "neq"
  | "in"
  | "not.in"
  | "empty"
  | "not.empty"
  | "lt"
  | "lte"
  | "gt"
  | "gte"
  | "between"
  | "relative"

JoinOperator

Join operator type for combining multiple filters.

type JoinOperator = "and" | "or" | "mixed"

Extended Types

ExtendedColumnFilter

Extended column filter with additional metadata.

interface ExtendedColumnFilter<TData> {
  id: Extract<keyof TData, string>
  value: string | string[]
  variant: FilterVariant
  operator: FilterOperator
  filterId: string
  joinOperator?: JoinOperator // Individual join operator for each filter
}

ExtendedColumnSort

Extended column sort for URL state management.

interface ExtendedColumnSort<TData> {
  id: Extract<keyof TData, string>
  desc: boolean
}

GlobalFilter

Global filter type.

type GlobalFilter = string | Record<string, unknown>

Column Definition Types

DataTableColumnDef

Extended column definition for data table. Inherits all TanStack Table ColumnDef properties.

type DataTableColumnDef<TData, TValue = unknown> = ColumnDef<
  DataTableFeatures,
  TData,
  TValue
>

For static columns, createDataTableColumnHelper<TData>() is the runtime counterpart: it pre-binds DataTableFeatures the same way this alias does, and cells get a typed getValue(). Helper results mix per-column value types, so pass them as DataTableColumns<TData> (what DataTableRoot accepts). Plain DataTableColumnDef<TData>[] arrays stay the better fit for dynamic columns and copy-paste examples.

import { createDataTableColumnHelper } from "@/components/niko-table/lib/data-table-features"

const columnHelper = createDataTableColumnHelper<Product>()
const columns = [
  columnHelper.accessor("price", {
    cell: ({ getValue }) => getValue().toFixed(2),
  }),
]

DataTableColumns

Mixed column arrays for DataTableRoot. Helper columns each carry their own TValue, so they are not assignable to DataTableColumnDef<TData>[] (that alias defaults TValue to unknown). Use this alias instead.

type DataTableColumns<TData> = DataTableColumnDef<TData, any>[]

ColumnMeta

Extended column metadata interface (augments TanStack Table’s ColumnMeta).

interface ColumnMeta<TData extends RowData, TValue> {
  // Display
  label?: string
  placeholder?: string

  // Filtering
  variant?: FilterVariant
  options?: Option[]
  range?: [number, number]
  autoOptions?: boolean
  autoOptionsFormat?: boolean
  /** Per-column label formatter for auto-derived faceted-filter options.
   *  Wins over `autoOptionsFormat`; ignored when caller passes explicit `options`. */
  formatOptionLabel?: (value: string) => string
  showCounts?: boolean
  dynamicCounts?: boolean
  mergeStrategy?: "preserve" | "augment" | "replace"

  // Formatting
  unit?: string
  icon?: React.ComponentType<{ className?: string }>

  // Layout
  /** Controls which column absorbs leftover row width (flex fill).
   *  Fill is on by default for resizable tables — the first non-pinned,
   *  resizable data column flexes automatically. Set `true` to make THIS
   *  column the one that fills instead of the default; set `false` to opt a
   *  column out of ever being auto-picked. Pure layout — never written to
   *  `columnSizing`. */
  flex?: boolean

  // Row Expansion
  expandedContent?: (row: TData) => React.ReactNode
}

TableMeta

Extended table metadata interface (augments TanStack Table’s TableMeta).

interface TableMeta<TData extends RowData> {
  joinOperator?: JoinOperator
  hasIndividualJoinOperators?: boolean
  /** Turns flex fill off for the whole table. Flex fill (the first resizable
   *  data column absorbing leftover row width) is on by default when column
   *  resizing is enabled; set `true` for a wide table meant to scroll
   *  horizontally rather than fill its container. */
  disableFlexFill?: boolean
}

Pass table metadata through the table-level meta option on DataTableRoot — not a column’s meta:

<DataTableRoot data={data} columns={columns} meta={{ disableFlexFill: true }}>

disableFlexFill is read when the table options are built, so set it statically rather than toggling it at runtime.

Row Types

DataTableRow

Data table row type. Alias for TanStack Table’s Row, pre-bound to DataTable’s feature set.

type DataTableRow<TData> = Row<DataTableFeatures, TData>

DataTableInstance

Data table instance type. Alias for TanStack Table’s Table, pre-bound to DataTable’s feature set.

type DataTableInstance<TData> = Table<DataTableFeatures, TData>

Query State Types

QueryKeys

Query keys for URL state management.

interface QueryKeys {
  page?: string
  perPage?: string
  sort?: string
  filters?: string
  joinOperator?: string
}

Type Helpers

ValueOf

Utility type to get the literal values from constant objects.

type ValueOf<T> = T[keyof T]

JoinOperatorValues

Convenience type for accessing JOIN_OPERATORS constant values.

type JoinOperatorValues = typeof JOIN_OPERATORS

FilterOperatorValues

Convenience type for accessing FILTER_OPERATORS constant values.

type FilterOperatorValues = typeof FILTER_OPERATORS

FilterVariantValues

Convenience type for accessing FILTER_VARIANTS constant values.

type FilterVariantValues = typeof FILTER_VARIANTS

TanStack Table Module Augmentation

The types module augments TanStack Table’s type definitions to add custom metadata:

• ColumnMeta - Adds label, placeholder, variant, options, flex (layout fill), and other filter-related metadata
• TableMeta - Adds joinOperator, hasIndividualJoinOperators for filter logic, and disableFlexFill for layout

This allows TypeScript to provide proper type checking and autocomplete for column and table metadata throughout the data table components.