Library Utilities

Utility functions, constants, and helper functions for the data table.

The lib/ directory contains utility functions, constants, and helper functions used throughout the data table components.

Constants

Centralized constants for join operators, filter operators, filter variants, and UI configuration.

Source Code ↗

JOIN_OPERATORS

Join operators for combining multiple filters.

Constant	Value	Description
`AND`	`"and"`	Logical AND (all filters must match)
`OR`	`"or"`	Logical OR (any filter can match)
`MIXED`	`"mixed"`	Mixed logic (combination of AND/OR)

FILTER_OPERATORS

Filter operator constants defining the comparison logic. Naming follows SQL/PostgREST standards.

Constant	Value	Description
`ILIKE`	`"ilike"`	SQL ILIKE (Case-insensitive search)
`NOT_ILIKE`	`"not.ilike"`	SQL NOT ILIKE
`EQ`	`"eq"`	SQL EQUAL (=)
`NEQ`	`"neq"`	SQL NOT EQUAL (!=)
`IN`	`"in"`	SQL IN (one of)
`NOT_IN`	`"not.in"`	SQL NOT IN (none of)
`EMPTY`	`"empty"`	Value is null or empty string
`NOT_EMPTY`	`"not.empty"`	Value is not null and not empty string
`LT`	`"lt"`	SQL LESS THAN (<)
`LTE`	`"lte"`	SQL LESS THAN OR EQUAL (<=)
`GT`	`"gt"`	SQL GREATER THAN (>)
`GTE`	`"gte"`	SQL GREATER THAN OR EQUAL (>=)
`BETWEEN`	`"between"`	SQL BETWEEN (range)
`RELATIVE`	`"relative"`	Relative date calculation (e.g., “today”)

FILTER_VARIANTS

Filter variant constants defining the UI control type.

Constant	Value	Description
`TEXT`	`"text"`	Standard text input
`NUMBER`	`"number"`	Numeric input
`RANGE`	`"range"`	Two-value range input
`DATE`	`"date"`	Single date picker
`DATE_RANGE`	`"dateRange"`	Date range picker
`SELECT`	`"select"`	Single select dropdown
`MULTI_SELECT`	`"multiSelect"`	Multi-select dropdown
`BOOLEAN`	`"boolean"`	Checkbox or toggle

DEFAULT_VALUES

Global default values.

Property	Value	Description
`JOIN_OPERATOR`	`JOIN_OPERATORS.AND`	Default join operator
`PAGE_SIZE`	`10`	Default page size
`PAGE_INDEX`	`0`	Default page index

UI_CONSTANTS

UI-related constraints and settings.

Property	Value	Description
`FILTER_ID_MAX_LENGTH`	`100`	Max characters allowed for a filter ID
`MAX_FILTER_DISPLAY_HEIGHT`	`300`	Default max height for scrollable filter popovers
`DEBOUNCE_DELAY`	`300`	Default debounce delay in milliseconds for search inputs

KEYBOARD_SHORTCUTS

Default keyboard shortcut key mappings.

Property	Value	Description
`FILTER_TOGGLE`	`"f"`	Open/Toggle filter menu
`FILTER_REMOVE`	`"f"`	Remove active filter (with Shift)
`ESCAPE`	`"escape"`	Close active UI elements
`ENTER`	`"enter"`	Confirm or submit active action
`BACKSPACE`	`"backspace"`	Remove character or navigate back
`DELETE`	`"delete"`	Item deletion

Data Table Utilities

Helper functions for filter operations and validation.

Source Code ↗

getFilterOperators

Get available filter operators for a given filter variant.

1
import { getFilterOperators } from "@/components/niko-table/lib/data-table"
2
import { FILTER_VARIANTS } from "@/components/niko-table/lib/constants"
3

4
const textOperators = getFilterOperators(FILTER_VARIANTS.TEXT)
5
// Returns: [{ label: "Contains", value: "ilike" }, ...]

Parameters

Name	Type	Description
`filterVariant`	`FilterVariant`	The filter variant type

Returns

Array of operator objects with label and value properties.

Type: Array<{ label: string; value: FilterOperator }>

getDefaultFilterOperator

Get the default filter operator for a given filter variant.

1
import { getDefaultFilterOperator } from "@/components/niko-table/lib/data-table"
2
import { FILTER_VARIANTS } from "@/components/niko-table/lib/constants"
3

4
const defaultOp = getDefaultFilterOperator(FILTER_VARIANTS.TEXT)
5
// Returns: "ilike"

Parameters

Name	Type	Description
`filterVariant`	`FilterVariant`	The filter variant type

Returns

FilterOperator - The default operator for the variant.

getValidFilters

Filter out invalid filters from an array.

1
import { getValidFilters } from "@/components/niko-table/lib/data-table"
2

3
const validFilters = getValidFilters(filters)
4
// Returns: ExtendedColumnFilter<TData>[] with only valid filters

Parameters

Name	Type	Description
`filters`	`ExtendedColumnFilter<TData>[]`	Array of filters to validate

Returns

ExtendedColumnFilter<TData>[] - Array containing only valid filters.

Format Utilities

Formatting functions for dates, labels, and query strings.

Source Code ↗

formatDate

Format a date value into a human-readable string.

1
import { formatDate } from "@/components/niko-table/lib/format"
2

3
formatDate(new Date())
4
// Returns: "January 1, 2024"
5

6
formatDate(new Date(), { month: "short", day: "numeric" })
7
// Returns: "Jan 1"

Parameters

Name	Type	Default	Description
`date`	`Date \| string \| number \| undefined`	-	Date value to format
`opts`	`Intl.DateTimeFormatOptions`	`{}`	Formatting options

Returns

string - Formatted date string, or empty string if date is invalid.

formatLabel

Format a value into a human-readable label. Capitalizes first letter of each word and replaces hyphens/underscores with spaces.

1
import { formatLabel } from "@/components/niko-table/lib/format"
2

3
formatLabel("firstName") // "FirstName"
4
formatLabel("first-name") // "First Name"
5
formatLabel("first_name") // "First Name"
6
formatLabel("true") // "Yes"
7
formatLabel("false") // "No"

Parameters

Name	Type	Description
`value`	`string`	Value to format

Returns

string - Formatted label string.

daysAgo

Create a date relative to the current date by subtracting days.

1
import { daysAgo } from "@/components/niko-table/lib/format"
2

3
daysAgo(7) // 7 days ago
4
daysAgo(30) // 30 days ago (1 month)
5
daysAgo(365) // 365 days ago (1 year)

Parameters

Name	Type	Description
`days`	`number`	Number of days to subtract

Returns

Date - Date object representing the date N days ago.

formatQueryString

Format URL query parameters into a human-readable query string for display.

1
import { formatQueryString } from "@/components/niko-table/lib/format"
2

3
const urlParams = { search: "i", globalFilter: { filters: [...], joinOperator: "mixed" } }
4
const urlKeys = { search: "search", globalFilter: "global" }
5
formatQueryString(urlParams, urlKeys)
6
// Returns: "?search=i&global={"filters":[...], "joinOperator":"mixed"}"

Parameters

Name	Type	Description
`urlParams`	`Record<string, unknown>`	The parsed URL parameters object
`urlKeys`	`Record<string, string>`	Mapping of parameter keys to URL query keys

Returns

string - Formatted query string (e.g., ?search=i&global={"filters":[...]}).

Filter Functions

Custom filter functions for TanStack Table with performance optimizations.

Source Code ↗

The filter functions module provides optimized filter implementations for TanStack Table. It includes:

Regex caching - Caches compiled regex patterns for 70-90% faster filter execution
Operator support - Implements all filter operators (ilike, eq, neq, in, between, etc.)
Performance optimizations - LRU-style cache eviction to prevent memory leaks

Performance Notes

The filter functions use regex caching to improve performance:

Without caching: 1,000 rows × 10 columns = 10,000 regex creations per search keystroke (~100-500ms)
With caching: First search creates regex once, subsequent searches reuse cached regex (~5-20ms)

The cache has a maximum size of 100 entries and uses LRU-like eviction to prevent memory leaks.

extendedFilter

Custom filter function for TanStack Table that supports all filter operators (ilike, eq, neq, in, not_in, between, lt, gt, lte, gte, empty, not_empty). Used as the default filterFn for columns with advanced filtering.

1
import { extendedFilter } from "@/components/niko-table/lib/filter-functions"
2

3
const columns = [
4
  {
5
    accessorKey: "name",
6
    filterFn: extendedFilter,
7
  },
8
]

globalFilter

Custom global filter function that searches across all visible columns. Supports debounced search input.

1
import { globalFilter } from "@/components/niko-table/lib/filter-functions"
2

3
const table = useReactTable({
4
  globalFilterFn: globalFilter,
5
})

numberRangeFilter

Filter function for numeric range columns. Filters rows where the value is between a [min, max] range.

1
import { numberRangeFilter } from "@/components/niko-table/lib/filter-functions"
2

3
const columns = [
4
  {
5
    accessorKey: "price",
6
    filterFn: numberRangeFilter,
7
  },
8
]

dateRangeFilter

Filter function for date range columns. Filters rows where the date falls between a start and end date.

1
import { dateRangeFilter } from "@/components/niko-table/lib/filter-functions"
2

3
const columns = [
4
  {
5
    accessorKey: "createdAt",
6
    filterFn: dateRangeFilter,
7
  },
8
]

createFilterValue

Utility to create a properly typed filter value object from an ExtendedColumnFilter. Used internally by the filter menu and inline filter components.

1
import { createFilterValue } from "@/components/niko-table/lib/filter-functions"
2

3
const filterValue = createFilterValue(filter)

processFiltersForLogic

Processes an array of ExtendedColumnFilter objects and groups them by join operator (AND/OR) for TanStack Table’s column filter state. Returns processed filters and the join operator map.

1
import { processFiltersForLogic } from "@/components/niko-table/lib/data-table"
2

3
const { processedFilters, joinOperators } = processFiltersForLogic(filters)

Style Utilities

Helper functions for styling table components, particularly for column pinning.

Source Code ↗

getCommonPinningStyles

Returns CSS styles for pinned columns (sticky positioning, z-index, shadows). Used internally by DataTable components, but available for custom implementations.

1
import { getCommonPinningStyles } from "@/components/niko-table/lib/styles"
2

3
// In a custom header cell
4
const pinningStyles = getCommonPinningStyles(column, true)
5

6
// In a custom body cell
7
const pinningStyles = getCommonPinningStyles(column, false)

Parameters

Name	Type	Default	Description
`column`	`Column<TData>`	-	TanStack Table column instance
`isHeader`	`boolean`	`false`	Whether this is a header cell (sets `top: 0` for vertical stickiness and z-index 20)

Returns

React.CSSProperties - CSS styles object with sticky positioning, z-index, background, and shadow.

Style Properties Applied:

position: sticky - Keeps column fixed during horizontal scroll
top - Set to 0 for header cells so they stick when the table scrolls vertically (sticky header)
left or right - Calculated position based on pinning side
zIndex - 20 for headers, 10 for body cells
backgroundColor - Uses var(--background) for opaque overlay
boxShadow - Visual separator using var(--border) for pinned column edges

Scroll Handler Factory

Shared scroll-listener body used by every data-table body component (DataTableBody, DataTableVirtualizedBody, DataTableVirtualizedDndBody, DataTableVirtualizedDndColumnBody). Extracted so scroll math changes propagate to all four bodies and so consumers writing custom bodies can reuse the canonical implementation.

Source Code ↗

createScrollHandler

Builds a passive-listener-friendly scroll handler that reads container metrics on each scroll event and dispatches:

onScroll with a ScrollEvent snapshot (scrollTop, scrollHeight, clientHeight, isTop, isBottom, percentage)
onScrolledTop when scrollTop === 0
onScrolledBottom when within scrollThreshold pixels of the end

Returned listener is intended to be attached with addEventListener("scroll", handler, { passive: true }) so the browser can keep scroll on its compositor thread (smoother on mobile and during virtual scroll).

1
import { createScrollHandler } from "@/components/niko-table/lib/create-scroll-handler"
2

3
React.useEffect(() => {
4
  const container = containerRef.current
5
  if (!container) return
6
  if (!onScroll && !onScrolledTop && !onScrolledBottom) return
7

8
  const handleScroll = createScrollHandler({
9
    onScroll,
10
    onScrolledTop,
11
    onScrolledBottom,
12
    scrollThreshold: 50,
13
  })
14
  container.addEventListener("scroll", handleScroll, { passive: true })
15
  return () => container.removeEventListener("scroll", handleScroll)
16
}, [onScroll, onScrolledTop, onScrolledBottom])

Parameters

Single options object:

Name	Type	Default	Description
`onScroll`	`(event: ScrollEvent) => void` (optional)	-	Called on every scroll event with a snapshot of container metrics
`onScrolledTop`	`() => void` (optional)	-	Called when `scrollTop === 0`
`onScrolledBottom`	`() => void` (optional)	-	Called when within `scrollThreshold` of the bottom
`scrollThreshold`	`number`	`50`	Pixel distance from the bottom that triggers `onScrolledBottom` (use a higher value for earlier prefetching)

Returns

(event: Event) => void — the listener to attach. Closure deps are stable across renders (the consumer-supplied callbacks are passed once at construction time), so wrap the construction in a useEffect keyed on the same callbacks.

Notes

For virtualized infinite scroll, prefer DataTableVirtualizedBody’s onNearEnd + prefetchThreshold props over onScrolledBottom — onNearEnd is virtualizer-index-driven (catches fast scrolls, scrollbar drag, programmatic scrollToIndex() jumps, and initial renders where the dataset doesn’t fill the viewport).
The handler reads event.currentTarget, so it must be attached directly to the scroll container — not to a parent.

Row Click Guard

Shared row-click guard used by every body component (DataTableBody, DataTableDndBody, DataTableDndColumnBody, DataTableVirtualizedBody, DataTableVirtualizedDndBody, DataTableVirtualizedDndColumnBody). Centralized so the interactive-element list (action buttons, checkboxes, links, radix collection items, etc.) stays in sync — adding a new data-slot to ignore means editing one file instead of six.

Source Code ↗

isInteractiveClickTarget

Returns true when the click landed on (or inside) an interactive element that should suppress the row-level onRowClick. Used by the per-row variants (DataTableBody, DataTableVirtualizedBody) which already know which row was clicked from event.currentTarget.dataset.rowId.

1
import { isInteractiveClickTarget } from "@/components/niko-table/lib/row-click"
2

3
const handleRowClick = (event: React.MouseEvent<HTMLElement>) => {
4
  if (isInteractiveClickTarget(event.target as HTMLElement)) return
5
  const rowId = event.currentTarget.dataset.rowId
6
  if (!rowId) return
7
  const row = table.getRow(rowId)
8
  if (!row) return
9
  onRowClick(row.original, event)
10
}

resolveRowFromClick

For delegated <tbody> handlers (used by the DnD bodies). Returns the matched row, or null if the click should be ignored — either it landed on an interactive descendant or no row could be resolved from the closest tr[data-row-id].

1
import { resolveRowFromClick } from "@/components/niko-table/lib/row-click"
2

3
const handleRowClick = (event: React.MouseEvent<HTMLElement>) => {
4
  const row = resolveRowFromClick(event.target as HTMLElement, table)
5
  if (!row) return
6
  onRowClick(row.original, event)
7
}

Notes

The interactive-element list lives in isInteractiveClickTarget — extend it there to add new ignored elements.
Rows must carry data-row-id={row.id} for delegated resolution to work. All built-in bodies do this; custom bodies should follow suit.

Additional Constants

SYSTEM_COLUMN_IDS

System column IDs used for smart pinning and feature detection. These are the IDs for special columns like row selection and row expansion.

1
import { SYSTEM_COLUMN_IDS } from "@/components/niko-table/lib/constants"
2

3
// Available IDs:
4
SYSTEM_COLUMN_IDS.SELECT // "select" - Row selection checkbox column
5
SYSTEM_COLUMN_IDS.EXPAND // "expand" - Row expansion toggle column

SYSTEM_COLUMN_ID_LIST

Array version of SYSTEM_COLUMN_IDS values. Useful for filtering or checking if a column ID is a system column.

1
import { SYSTEM_COLUMN_ID_LIST } from "@/components/niko-table/lib/constants"
2

3
// ["select", "expand"]
4
const isSystemColumn = SYSTEM_COLUMN_ID_LIST.includes(columnId)

ERROR_MESSAGES

Standard error messages used throughout the library for consistent error reporting.

1
import { ERROR_MESSAGES } from "@/components/niko-table/lib/constants"
2

3
// Available messages:
4
ERROR_MESSAGES.DEPRECATED_GLOBAL_JOIN_OPERATOR

Faceted Options Builder

Used internally by faceted-filter components to translate a raw column dataset into the { label, value, count } shape the filter UI consumes. Documented for completeness — most consumers won’t import it directly.

Source Code ↗

buildFacetedOptions

Walks a TanStack Table column / row set and produces deduplicated { label, value, count } entries for the faceted-filter dropdown. Honors the dynamicCounts flag so counts update reactively when other filters change. Used internally by DataTableFacetedFilter and TableColumnFacetedFilter.

1
import { buildFacetedOptions } from "@/components/niko-table/lib/build-faceted-options"
2

3
const options = buildFacetedOptions({
4
  rows: table.getCoreRowModel().rows,
5
  columnId: "category",
6
  dynamicCounts: true,
7
})
8
// → [{ label: "Electronics", value: "electronics", count: 12 }, ...]

Notes

This module is consumed by the faceted-filter wrappers; if you’re building a custom faceted UI, useGeneratedOptions (in hooks/) is the consumer-facing surface that wraps this helper with React state.
Runs in O(n) over the column’s cell values; safe to call per render for typical column counts.

Row Filtering Helpers

Internal helpers that resolve globalFilter / column-filter combinations to a final visible row set. Used by DataTableRoot when wiring tableOptions.getFilteredRowModel.

Source Code ↗

filter-rows.ts

Provides the row-filtering logic that backs the table’s filtered row model — combines per-column filters with the global filter, applies the right extendedFilter / globalFilter / numberRangeFilter / dateRangeFilter based on column meta, and returns the visible row set.

This module is internal to the table’s filter pipeline. Consumers normally interact with it indirectly via tableOptions.filterFns (which DataTableRoot wires automatically). If you’re building a fully custom filter pipeline you can import the named helpers from this file directly — see the source for the current export surface.

Library Utilities

Constants

JOIN_OPERATORS

FILTER_OPERATORS

FILTER_VARIANTS

DEFAULT_VALUES

UI_CONSTANTS

KEYBOARD_SHORTCUTS

Data Table Utilities

getFilterOperators

Parameters

Returns

getDefaultFilterOperator

Parameters

Returns

getValidFilters

Parameters

Returns

Format Utilities

formatDate

Parameters

Returns

formatLabel

Parameters

Returns

daysAgo

Parameters

Returns

formatQueryString

Parameters

Returns

Filter Functions

Performance Notes

extendedFilter

globalFilter

numberRangeFilter

dateRangeFilter

createFilterValue

processFiltersForLogic

Style Utilities

getCommonPinningStyles

Parameters

Returns

Scroll Handler Factory

createScrollHandler

Parameters

Returns

Notes

Row Click Guard

isInteractiveClickTarget

resolveRowFromClick

Notes

Additional Constants

SYSTEM_COLUMN_IDS

SYSTEM_COLUMN_ID_LIST

ERROR_MESSAGES

Faceted Options Builder

buildFacetedOptions

Notes

Row Filtering Helpers

filter-rows.ts

Getting Started

Niko Table

Examples

Contributing