User-Facing Components

User-facing components are context-aware and automatically connect to the table via the useDataTable hook. These are the recommended components for most use cases.

DataTableToolbarSection

Container for organizing filters and actions in the toolbar.

Source Code ↗

import { DataTableToolbarSection } from "@/components/niko-table/components"

<DataTableToolbarSection className="flex justify-between">
  <DataTableSearchFilter />
  <DataTableViewMenu />
</DataTableToolbarSection>

Props

Name	Type	Default	Description
className	string	-	Additional CSS classes.
children	React.ReactNode	-	Filter and action components.

DataTablePagination

Full-featured pagination controls with page size selection and navigation.

Source Code ↗

Filter Implementation ↗

import { DataTablePagination } from "@/components/niko-table/components"

<DataTablePagination
  pageSizeOptions={[10, 25, 50, 100]}
  totalCount={500}
  onPageChange={pageIndex => console.log("Page:", pageIndex)}
/>

Props

Name	Type	Default	Description
pageSizeOptions	number[]	[10, 25, 50, 100]	Available page size options.
totalCount	number	-	Total count of items (for server-side pagination).
isLoading	boolean	-	Loading state (overrides context loading).
isFetching	boolean	-	Fetching state (for TanStack Query).
disableNextPage	boolean	-	Explicitly disable next page button.
disablePreviousPage	boolean	-	Explicitly disable previous page button.
className	string	-	Additional CSS classes.

Event Handlers

Name	Type	Description
onPageChange	(pageIndex: number) => void	Called when page changes.
onNextPage	(pageIndex: number) => void	Called when navigating to next page.
onPreviousPage	(pageIndex: number) => void	Called when navigating to previous page.
onPageSizeChange	(pageSize: number, pageIndex: number) => void	Called when page size changes.
onPaginationReady	() => void	Called when pagination is initialized.

Note: Pagination buttons are automatically disabled when isLoading or isFetching is true.

DataTableSearchFilter

Global search input with debouncing. Supports both controlled and uncontrolled modes.

Source Code ↗

Filter Implementation ↗

import { DataTableSearchFilter } from "@/components/niko-table/components"

// Uncontrolled (manages its own state)
<DataTableSearchFilter placeholder="Search products..." />

// Controlled (you manage the state)
const [search, setSearch] = useState("")
<DataTableSearchFilter
  value={search}
  onChange={setSearch}
  placeholder="Search..."
/>

// With nuqs for URL state
const [search, setSearch] = useQueryState('search')
<DataTableSearchFilter
  value={search ?? ""}
  onChange={setSearch}
/>

Props

Name	Type	Default	Description
placeholder	string	"Search..."	Input placeholder text.
value	string	-	Controlled value.
onChange	(value: string) => void	-	Change handler for controlled mode.
showClearButton	boolean	true	Show clear button when input has value.
className	string	-	Additional CSS classes.

DataTableFilterMenu

Command palette-style interface for adding filters with advanced operators and AND/OR logic.

Source Code ↗

Filter Implementation ↗

import { DataTableFilterMenu } from "@/components/niko-table/components"

<DataTableFilterMenu
  autoOptions
  dynamicCounts
  showCounts
  mergeStrategy="augment"
/>

Props

Name	Type	Default	Description
autoOptions	boolean	true	Auto-generate options for select/multi_select columns.
showCounts	boolean	true	Show counts beside each option.
dynamicCounts	boolean	true	Recompute counts based on filtered rows.
limitToFilteredRows	boolean	true	Generate options from filtered rows only.
includeColumns	string[]	-	Only generate options for these column ids.
excludeColumns	string[]	-	Exclude these column ids from generation.
limitPerColumn	number	-	Limit number of generated options per column.
mergeStrategy	"preserve" | "augment" | "replace"	"preserve"	How to handle existing static options.
className	string	-	Additional CSS classes.

Merge Strategy

Value	Description
preserve	Keep user-defined options untouched (default).
augment	Add counts to matching values from static options.
replace	Override static options with generated options.

DataTableFacetedFilter

Faceted filter component for single or multiple selection with dynamic option generation.

Source Code ↗

Filter Implementation ↗

import { DataTableFacetedFilter } from "@/components/niko-table/components"

// With static options
<DataTableFacetedFilter
  accessorKey="category"
  title="Category"
  options={[
    { label: "Electronics", value: "electronics" },
    { label: "Clothing", value: "clothing" },
  ]}
  multiple
/>

// Auto-generate options from data
<DataTableFacetedFilter
  accessorKey="brand"
  limitToFilteredRows={true}
/>

Props

Name	Type	Default	Description
accessorKey	keyof TData & string	-	Column accessor key (required).
title	string	-	Custom title (uses column.meta.label if not provided).
options	Option[]	-	Static options array.
multiple	boolean	-	Allow multiple selection.
showCounts	boolean	true	Show counts beside each option.
dynamicCounts	boolean	true	Recompute counts based on filtered rows.
limitToFilteredRows	boolean	true	Show only options from filtered rows.

limitToFilteredRows

Controls whether the filter shows options from all data or only from filtered rows.

• true (default): Options are generated from rows that match other active filters. Useful for filters like “Brand” where you want to see only relevant options.
• false: Options are generated from all rows, regardless of other filters. Useful for filters like “Category” where you want to see all available options.

DataTableSortMenu

Menu for managing column sorting with drag-and-drop reordering.

Source Code ↗

Filter Implementation ↗

import { DataTableSortMenu } from "@/components/niko-table/components"

<DataTableSortMenu className="ml-auto" />

Props

Name	Type	Default	Description
className	string	-	Additional CSS classes.
debounceMs	number	-	Debounce delay for sort updates.
throttleMs	number	-	Throttle delay for sort updates.
shallow	boolean	-	Use shallow comparison for sort state.
onSortingChange	(sorting: ColumnSort[]) => void	-	Callback when sorting changes.

DataTableViewMenu

Column visibility toggle menu with search functionality.

Source Code ↗

Filter Implementation ↗

import { DataTableViewMenu } from "@/components/niko-table/components"

<DataTableViewMenu />

Props

Name	Type	Default	Description
className	string	-	Additional CSS classes.
onColumnVisibilityChange	(columnId: string, isVisible: boolean) => void	-	Callback when visibility changes.

DataTableInlineFilter

Inline filter toolbar for managing filters with advanced operators and AND/OR logic.

Source Code ↗

Filter Implementation ↗

import { DataTableInlineFilter } from "@/components/niko-table/components"

<DataTableInlineFilter
  autoOptions
  dynamicCounts
  showCounts
  mergeStrategy="augment"
/>

Props

Same as DataTableFilterMenu. See DataTableFilterMenu section above for details.

DataTableSliderFilter

Slider filter for numeric ranges with min/max inputs.

Source Code ↗

Filter Implementation ↗

import { DataTableSliderFilter } from "@/components/niko-table/components"

// Auto-detect from column metadata
<DataTableSliderFilter accessorKey="price" />

// Custom range
<DataTableSliderFilter
  accessorKey="rating"
  min={1}
  max={5}
  step={0.5}
/>

// With unit
<DataTableSliderFilter
  accessorKey="price"
  range={[0, 1000]}
  unit="$"
/>

Props

Name	Type	Default	Description
accessorKey	keyof TData & string	-	Column accessor key (required).
title	string	-	Custom title.
min	number	-	Minimum value (auto-detected from data if not provided).
max	number	-	Maximum value (auto-detected from data if not provided).
step	number	1	Step increment.
range	[number, number]	-	Range array [min, max] (overrides min/max).
unit	string	-	Unit label (e.g., ”$”, “kg”).

DataTableDateFilter

Date filter component for single dates or date ranges.

Source Code ↗

Filter Implementation ↗

import { DataTableDateFilter } from "@/components/niko-table/components"

// Single date
<DataTableDateFilter accessorKey="releaseDate" />

// Date range
<DataTableDateFilter
  accessorKey="releaseDate"
  multiple
/>

Props

Name	Type	Default	Description
accessorKey	keyof TData & string	-	Column accessor key (required).
title	string	-	Custom title.
multiple	boolean	false	Enable date range selection.

DataTableClearFilter

Button to clear all active filters, sorting, and search.

Source Code ↗

Filter Implementation ↗

import { DataTableClearFilter } from "@/components/niko-table/components"

<DataTableClearFilter />

Props

Name	Type	Default	Description
variant	ButtonVariant	"outline"	Button variant.
size	ButtonSize	"sm"	Button size.
showIcon	boolean	true	Show clear icon.
children	React.ReactNode	-	Button content.
enableResetColumnFilters	boolean	true	Enable resetting column filters.
enableResetGlobalFilter	boolean	true	Enable resetting global filter (search).
enableResetSorting	boolean	true	Enable resetting sorting.
className	string	-	Additional CSS classes.

DataTableExportButton

Button to export table data to CSV.

Source Code ↗

Filter Implementation ↗

import { DataTableExportButton } from "@/components/niko-table/components"

// Basic usage

<DataTableExportButton filename="products" />

// With human-readable headers from column.meta.label

<DataTableExportButton filename="products" useHeaderLabels />

// Export only selected rows

<DataTableExportButton filename="selected" onlySelected />

Props

Name	Type	Default	Description
filename	string	"table"	Filename for exported CSV (without extension).
excludeColumns	(keyof TData)[]	-	Columns to exclude from export.
onlySelected	boolean	false	Export only selected rows.
useHeaderLabels	boolean	false	Use column.columnDef.meta.label as CSV headers instead of column IDs.
variant	ButtonVariant	"outline"	Button variant.
size	ButtonSize	"sm"	Button size.
label	string	"Export CSV"	Button label.
showIcon	boolean	true	Show download icon.
className	string	-	Additional CSS classes.

DataTableColumnHeader

Composable column header container. Provides layout for title, actions, and filters within each column header.

Source Code ↗

import {
  DataTableColumnHeader,
  DataTableColumnTitle,
  DataTableColumnSortMenu,
} from "@/components/niko-table/components"

const columns: DataTableColumnDef<User>[] = [
  {
    accessorKey: "name",
    header: () => (
      <DataTableColumnHeader>
        <DataTableColumnTitle />
        <DataTableColumnSortMenu />
      </DataTableColumnHeader>
    ),
    meta: { label: "Name" },
  },
]

Props

Name	Type	Description
children	React.ReactNode	Column header content.
className	string	Additional CSS classes.

Composition

The DataTableColumnHeader is composable. You can break it down into parts to customize the layout or add custom filters.

import {
  DataTableColumnHeader,
  DataTableColumnTitle,
  DataTableColumnActions,
  DataTableColumnFilter,
  DataTableColumnFilterTrigger,
  DataTableColumnSortOptions,
  DataTableColumnHideOptions,
  DataTableColumnPinOptions,
  DataTableColumnFacetedFilterOptions,
  DataTableColumnSliderFilterOptions,
  DataTableColumnDateFilterOptions,
} from "@/components/niko-table/components"

const columns: DataTableColumnDef<User>[] = [
  {
    accessorKey: "status",
    header: () => (
      <DataTableColumnHeader>
        <DataTableColumnTitle />
        <DataTableColumnActions>
          <DataTableColumnFilter>
            <DataTableColumnFilterTrigger />
            <DataTableColumnFacetedFilterOptions />
          </DataTableColumnFilter>
          <DataTableColumnSortOptions />
          <DataTableColumnPinOptions />
          <DataTableColumnHideOptions />
        </DataTableColumnActions>
      </DataTableColumnHeader>
    ),
    meta: { label: "Status" },
  },
]

Standalone filter menus can also be placed directly inside DataTableColumnHeader without needing DataTableColumnActions:

import {
  DataTableColumnHeader,
  DataTableColumnTitle,
  DataTableColumnSortMenu,
  DataTableColumnFacetedFilterMenu,
  DataTableColumnSliderFilterMenu,
  DataTableColumnDateFilterMenu,
} from "@/components/niko-table/components"
import { FILTER_VARIANTS } from "@/components/niko-table/lib"

const columns: DataTableColumnDef<Product>[] = [
  {
    accessorKey: "category",
    header: () => (
      <DataTableColumnHeader>
        <DataTableColumnTitle />
        <DataTableColumnSortMenu variant={FILTER_VARIANTS.TEXT} />
        <DataTableColumnFacetedFilterMenu
          multiple
          limitToFilteredRows={false}
        />
      </DataTableColumnHeader>
    ),
    meta: { label: "Category" },
    enableColumnFilter: true,
  },
  {
    accessorKey: "price",
    header: () => (
      <DataTableColumnHeader>
        <DataTableColumnTitle />
        <DataTableColumnSortMenu variant={FILTER_VARIANTS.NUMBER} />
        <DataTableColumnSliderFilterMenu />
      </DataTableColumnHeader>
    ),
    meta: { label: "Price", variant: "range" },
    enableColumnFilter: true,
  },
  {
    accessorKey: "releaseDate",
    header: () => (
      <DataTableColumnHeader>
        <DataTableColumnTitle />
        <DataTableColumnSortMenu />
        <DataTableColumnDateFilterMenu />
      </DataTableColumnHeader>
    ),
    meta: { label: "Release Date", variant: "date_range" },
    enableColumnFilter: true,
  },
]

How Context Works

When you use flexRender(...) in the core structure (like DataTableHeader or DataTableVirtualizedHeader), it renders the JSX returned by your header function. That JSX is automatically wrapped by the <DataTableColumnHeaderRoot column={...}> provider in the core components.

This means any component inside your header function (like DataTableColumnHeader, DataTableColumnTitle, etc.) correctly receives the column context even if you are using manual composition in your columns definition.

Advanced: Context Provider and Hook

For custom integrations, the column header context is available directly:

DataTableColumnHeaderRoot

Provider component that supplies column context to all child header components. This is used internally by DataTableHeader and DataTableVirtualizedHeader — you typically don’t need this unless building a completely custom header renderer.

import { DataTableColumnHeaderRoot } from "@/components/niko-table/components"

<DataTableColumnHeaderRoot column={column}>
  {/* All child components receive column context */}
  <DataTableColumnHeader>
    <DataTableColumnTitle />
  </DataTableColumnHeader>
</DataTableColumnHeaderRoot>

Name	Type	Description
column	Column<TData, TValue>	Table column instance (required).
children	React.ReactNode	Child components.

useColumnHeaderContext

Hook to access the column header context. Returns the current column instance. Use this when building custom sub-components that need access to the column.

import { useColumnHeaderContext } from "@/components/niko-table/components"

function CustomHeaderButton() {
  const { column } = useColumnHeaderContext(true)
  return <button onClick={() => column.toggleSorting()}>Sort</button>
}

Parameter	Type	Description
required	boolean	If true, throws if used outside DataTableColumnHeaderRoot.

Sub-Components

DataTableColumnTitle

Renders the column title (clickable to toggle sort). Uses column context automatically.

Name	Type	Default	Description
title	string	-	Custom title (uses column.meta.label if not provided).
className	string	-	Additional CSS classes.

DataTableColumnActions

Container for action icons and dropdown menu for column options. Automatically detects active state (sorted, pinned, filtered).

Name	Type	Default	Description
children	React.ReactNode	-	Action option components.
isActive	boolean	auto	Override active state (auto-detected from context).
className	string	-	Additional CSS classes.

DataTableColumnFilter

Wrapper for grouping column filter components.

Name	Type	Description
children	React.ReactNode	Filter components.
className	string	Additional CSS classes.

DataTableColumnFilterTrigger

Dedicated filter icon button that uses column context. Shows a funnel icon to open column filters.

Name	Type	Description
className	string	Additional CSS classes.

DataTableColumnSortOptions

Sorting options to compose inside DataTableColumnActions. Renders sort ascending/descending/clear options within a dropdown menu.

Name	Type	Default	Description
variant	SortIconVariant	"text"	Sort icon variant ("text", "number", "date"). Auto-detected from column.meta.variant.
withSeparator	boolean	true	Whether to render a separator before the options.
className	string	-	Additional CSS classes.

DataTableColumnSortMenu

Standalone sort button for inline use outside dropdown menus. Renders as a clickable button with a dropdown for sort options.

Name	Type	Default	Description
variant	SortIconVariant	"text"	Sort icon variant ("text", "number", "date"). Auto-detected from column.meta.variant.
className	string	-	Additional CSS classes.

DataTableColumnPinOptions

Pinning options to compose inside DataTableColumnActions. Renders pin left/right/unpin options.

Name	Type	Description
className	string	Additional CSS classes.

DataTableColumnPinMenu

Standalone pinning menu for column header. Renders as a clickable button.

Name	Type	Description
className	string	Additional CSS classes.

DataTableColumnHideOptions

Hide column option to compose inside DataTableColumnActions.

Name	Type	Description
className	string	Additional CSS classes.

DataTableColumnHideMenu

Standalone hide menu for column header. Renders as a clickable button.

Name	Type	Description
className	string	Additional CSS classes.

DataTableColumnFacetedFilterOptions

Faceted filter options to compose inside DataTableColumnActions. Shows a multi-select filter list.

Name	Type	Description
column	Column<TData>	Optional override (auto-detected from context).
options	Option[]	Static options array.
multiple	boolean	Allow multiple selection.
className	string	Additional CSS classes.

DataTableColumnFacetedFilterMenu

Standalone faceted filter popover for column header. Renders as a clickable button with filter icon. Auto-generates options from row data when no explicit options are provided.

Name	Type	Default	Description
column	Column<TData>	-	Optional override (auto-detected from context).
options	Option[]	-	Static options array (auto-generated if omitted).
multiple	boolean	-	Allow multiple selection.
limitToFilteredRows	boolean	true	Show only options from filtered rows (false = all rows).
className	string	-	Additional CSS classes.

DataTableColumnSliderFilterOptions

Slider filter options to compose inside DataTableColumnActions. Shows a range slider for numeric columns.

Name	Type	Description
column	Column<TData>	Optional override (auto-detected from context).
min	number	Minimum value.
max	number	Maximum value.
step	number	Step increment.
className	string	Additional CSS classes.

DataTableColumnSliderFilterMenu

Standalone slider filter popover for column header. Renders as a clickable button with slider icon.

Name	Type	Description
column	Column<TData>	Optional override (auto-detected from context).
min	number	Minimum value.
max	number	Maximum value.
step	number	Step increment.
className	string	Additional CSS classes.

DataTableColumnDateFilterOptions

Date filter options to compose inside DataTableColumnActions. Shows a date picker for date columns.

Name	Type	Description
column	Column<TData>	Optional override (auto-detected from context).
multiple	boolean	Enable date range selection.
className	string	Additional CSS classes.

DataTableColumnDateFilterMenu

Standalone date filter popover for column header. Renders as a clickable button with calendar icon.

Name	Type	Description
column	Column<TData>	Optional override (auto-detected from context).
multiple	boolean	Enable date range selection.
className	string	Additional CSS classes.

DataTableAside

Sidebar component for displaying additional content (filters, details, etc.) alongside the table.

Source Code ↗

import {
  DataTableAside,
  DataTableAsideTrigger,
  DataTableAsideContent,
  DataTableAsideHeader,
  DataTableAsideTitle,
  DataTableAsideDescription,
  DataTableAsideClose,
} from "@/components/niko-table/components"

<DataTableAside side="right">
  <DataTableAsideTrigger>Open Filters</DataTableAsideTrigger>
  <DataTableAsideContent>
    <DataTableAsideHeader>
      <DataTableAsideTitle>Filters</DataTableAsideTitle>
      <DataTableAsideDescription>Filter your data</DataTableAsideDescription>
      <DataTableAsideClose />
    </DataTableAsideHeader>
    {/* filter content */}
  </DataTableAsideContent>
</DataTableAside>

DataTableAside Props

Name	Type	Default	Description
children	React.ReactNode	-	Aside components (Trigger, Content).
side	"left" | "right"	"right"	Side of the table to display the aside.
open	boolean	-	Controlled open state.
onOpenChange	(open: boolean) => void	-	Callback when open state changes.
defaultOpen	boolean	false	Initial open state (uncontrolled).

DataTableAsideTrigger Props

Name	Type	Default	Description
children	React.ReactNode	-	Trigger content.
asChild	boolean	false	Render as child element.
className	string	-	Additional CSS classes.

DataTableAsideContent Props

Name	Type	Default	Description
children	React.ReactNode	-	Aside content.
width	string	"w-1/2"	Width of the aside (Tailwind class).
sticky	boolean	false	Make aside sticky.
className	string	-	Additional CSS classes.

DataTableSelectionBar

Shows bulk actions when rows are selected.

Source Code ↗

import { DataTableSelectionBar } from "@/components/niko-table/components"

<DataTableSelectionBar
  selectedCount={table.getSelectedRowModel().rows.length}
  onClear={() => table.resetRowSelection()}
>
  <Button onClick={handleDelete}>Delete Selected</Button>
  <Button onClick={handleExport}>Export Selected</Button>
</DataTableSelectionBar>

Props

Name	Type	Default	Description
selectedCount	number	-	Number of selected rows (required).
onClear	() => void	-	Callback to clear selection.
children	React.ReactNode	-	Custom action buttons.
className	string	-	Additional CSS classes.

DataTableEmptyState Components

Composition components for building custom empty states.

Source Code ↗

import {
  DataTableEmptyIcon,
  DataTableEmptyMessage,
  DataTableEmptyTitle,
  DataTableEmptyDescription,
  DataTableEmptyFilteredMessage,
  DataTableEmptyActions,
} from "@/components/niko-table/components"
import { PackageOpen } from "lucide-react"
import { Button } from "@/components/ui/button"

// Complete empty state composition

<DataTableEmptyBody>
  <DataTableEmptyIcon>
    <PackageOpen className="size-12 text-muted-foreground" />
  </DataTableEmptyIcon>
  <DataTableEmptyMessage>
    <DataTableEmptyTitle>No products found</DataTableEmptyTitle>
    <DataTableEmptyDescription>
      Get started by adding your first product to the catalog.
    </DataTableEmptyDescription>
  </DataTableEmptyMessage>
  <DataTableEmptyFilteredMessage>
    No products match your current filters. Try adjusting your search criteria.
  </DataTableEmptyFilteredMessage>
  <DataTableEmptyActions>
    <Button onClick={handleAddProduct}>Add Product</Button>
    <Button variant="outline" onClick={handleImport}>
      Import from CSV
    </Button>
  </DataTableEmptyActions>
</DataTableEmptyBody>

DataTableEmptyIcon

Icon component for empty state.

Name	Type	Description
children	React.ReactNode	Icon element.
className	string	Additional CSS classes.

DataTableEmptyMessage

Message shown when table is empty (not filtered).

Name	Type	Description
children	React.ReactNode	Message content.
className	string	Additional CSS classes.

DataTableEmptyFilteredMessage

Message shown when filters return no results.

Name	Type	Description
children	React.ReactNode	Message content.
className	string	Additional CSS classes.

DataTableEmptyTitle

Title component for empty state messages.

Name	Type	Description
children	React.ReactNode	Title text.
className	string	Additional CSS classes.

DataTableEmptyDescription

Description component for empty state messages.

Name	Type	Description
children	React.ReactNode	Description text.
className	string	Additional CSS classes.

DataTableEmptyActions

Actions component for empty state (buttons, links, etc.).

Name	Type	Description
children	React.ReactNode	Action buttons/links.
className	string	Additional CSS classes.