niko-table-best-practices
Integrate and use Niko Table (shadcn-compatible data tables with TanStack Table) and the editable Data Grid. Use when the user mentions Niko Table, niko-table.com, data table with shadcn, TanStack Table, building a sortable or filterable table, faceted filters, advanced filter menu, row or column drag-and-drop, server-side pagination, server-side grid, infinite scroll, Drizzle ORM, nuqs, URL state, shareable or bookmarkable table, row expansion, tree table, row selection, editable spreadsheet grid, useDataGrid, DataGrid cell editors, clipboard/fill handle, useGridChanges, or any shadcn-compatible data grid — even if they don't name Niko Table explicitly. Prefer this skill whenever the task involves a data table or editable grid in a React/shadcn project so the model follows Niko Table structure, imports, and patterns.
How do I install this agent skill?
npx skills add https://github.com/semkoo/niko-table-registry --skill niko-table-best-practicesIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a detailed integration guide and structural patterns for using the Niko Table UI library in React projects. It focuses on library-specific configurations, components, and best practices like server-side pagination, URL state management (nuqs), and data grid editing. No malicious code, external executable downloads, or data exfiltration patterns were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
1 file scanned · No issues
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
Niko Table Integration Guide
A skill for building and configuring data tables with Niko Table: structure, filters (search, faceted, advanced), column menus, DnD, server-side patterns, and the editable Data Grid.
At a high level:
- New table: DataTableRoot → ToolbarSection (optional) → DataTable → Header + Body (Skeleton, EmptyBody) → Pagination. Use direct file imports only (no barrel exports). Install
@niko-table/data-tablefor the owner; à-la-carte controls depend on@niko-table/data-table-core(context + structure, no Root) when you own the TanStack instance. - Adding filters: Toolbar = DataTableSearchFilter, DataTableFacetedFilter, DataTableFilterMenu. Column headers = DataTableColumnFacetedFilterMenu, DataTableColumnSliderFilterMenu, DataTableColumnDateFilterMenu. Set column
meta(variant, options, etc.) andenableColumnFilter: true. - Row/column DnD: Row DnD needs
getRowId, DataTableRowDndProvider outside DataTable; don’t combine row DnD with sorting/filtering. Column DnD is safe with everything. - Grouping: Mount
DataTableColumnGroupOptionsinDataTableColumnActions(orconfig.enableGrouping). UseaggregationFn/aggregatedCellfor rollups andgetGroupingValuefor buckets (e.g. month). Don’t combine with row DnD or with treegetSubRows— tree = nested data; grouping = flat rows bucketed by column. See Grouping Table / Tree Table on niko-table.com. - Server-side:
config.manualPagination/manualSorting/manualFiltering+config.pageCount, passtotalCountto DataTablePagination, and setmaxHeightonDataTableso page-size changes scroll. Structure it around a serializable wire contract — ONE functionfetch(query: { page, pageSize, sorting, search, columnFilters })→{ data, total, facets }— so any backend (SQL, Drizzle, Prisma, Supabase, REST) plugs in; see Server-Side Table example and the Drizzle ORM guide at niko-table.com. - URL state (nuqs): Wrap app with
NuqsAdapter; useuseQueryStateswith parsers for pagination, sort, filters, search; pass URL-derived state intoDataTableRootand wireonPaginationChange/onSortingChange/onColumnFiltersChange/onGlobalFilterChangetosetUrlParams. - Large lists: Use
DataTableVirtualizedBody(from core/structure) instead ofDataTableBodyfor 10k+ rows; same children (Skeleton, EmptyBody). See Virtualization Table example. - Sidebar: Use
DataTableAside(and trigger) for a detail panel next to the table. See Aside Table example. - Data Grid:
useDataGrid+<DataGrid grid={grid}>wrappingDataTableinsideDataTableRoot. Opt-in children for clipboard/fill/move. Cell editors via<DataGridCell>+Grid*Cell. Install@niko-table/data-table-grid(+data-table-grid-changesfor persistence). Mount<DataTableColumnResize />inside the grid so columns flex-fill the width, and passclassName="space-y-2 outline-none"to<DataGrid>for spacing. For grids backed by a server, don't paginate — stream chunks on scroll (see Server-Side patterns below). See Basic Grid / Data Grid docs on niko-table.com.
Your job when using this skill is to figure out where the user is — new table, adding filters/DnD/grouping, fixing imports, wiring server-side, URL state (nuqs), row expansion, tree table, row selection, or editable Data Grid — and give them the right structure, imports, and patterns. If they’re vague (“I want a table”), suggest the minimal template and point to niko-table.com for examples. If they already have a table and want faceted filters or the advanced filter menu, jump to the Filtering section. If they want spreadsheet editing, go to Data Grid. Stay flexible: some users want copy-paste snippets; others want to understand the two-layer (DataTable* vs Table*) pattern.
Full docs and examples: https://niko-table.com. Registry: https://niko-table.com/r/{name}.json in components.json under registries["@niko-table"].
Quick Reference
- Docs and examples: https://niko-table.com (installation, examples, API overview)
- Registry URL:
https://niko-table.com/r/{name}.json— add tocomponents.jsonunderregistries["@niko-table"]
Communicating with the user
Users may be new to Niko Table or to the shadcn/TanStack stack. When in doubt, briefly explain why direct imports matter (tree-shaking, no barrel files) and why getRowId is needed for row DnD. Mention that most DataTableRoot config is auto-detected from the components they use, so they only need to pass config when overriding or for manual/server-side. For deep reference (all add-ons, full API), point to niko-table.com.
When not to use: If the project clearly uses another table library (e.g. AG Grid, MUI Data Grid, TanStack Table without this registry), don’t force Niko Table — suggest the appropriate pattern for their stack.
Table Structure
All table UI must live inside DataTableRoot. Recommended composition:
DataTableRoot (required)
→ DataTableToolbarSection (optional: search, filters, view menu)
→ DataTable
→ DataTableHeader
→ DataTableBody
→ DataTableSkeleton (when loading)
→ DataTableEmptyBody (when no data)
→ DataTablePagination (optional)
Optional: Wrap the table (or DataTableRoot) in DataTableErrorBoundary from @/components/niko-table/core/data-table-error-boundary so render errors show a fallback UI instead of breaking the page.
Imports — No Barrel Exports
Use direct file paths only. Do not use index.ts re-exports for core, components, or filters.
| Purpose | Import path |
|---|---|
| Root & table | @/components/niko-table/core/data-table-root, @/components/niko-table/core/data-table |
| Structure | @/components/niko-table/core/data-table-structure (Header, Body, Skeleton, EmptyBody) |
| Toolbar / filters | @/components/niko-table/components/data-table-toolbar-section, data-table-search-filter, data-table-pagination, etc. |
| Types | @/components/niko-table/types (e.g. DataTableColumnDef) |
Examples:
import { DataTableRoot } from "@/components/niko-table/core/data-table-root"
import { DataTable } from "@/components/niko-table/core/data-table"
import {
DataTableHeader,
DataTableBody,
DataTableSkeleton,
DataTableEmptyBody,
} from "@/components/niko-table/core/data-table-structure"
import { DataTableToolbarSection } from "@/components/niko-table/components/data-table-toolbar-section"
import { DataTableSearchFilter } from "@/components/niko-table/components/data-table-search-filter"
import { DataTablePagination } from "@/components/niko-table/components/data-table-pagination"
import type { DataTableColumnDef } from "@/components/niko-table/types"
Two-Layer Component Pattern
- Components (
DataTable*): Context-aware; useuseDataTable()internally. Import fromcomponents/. Prefer these for normal usage (notableprop). - Filters (
Table*): Accepttableprop; import fromfilters/. Use when building custom components or managing the table instance yourself.
Use DataTable* components from their direct paths (e.g. data-table-pagination) for context-based usage; use Table* from filters when you need the low-level API.
Column Definitions
- Type:
DataTableColumnDef<TData>[]from@/components/niko-table/types. - Use
accessorKeyandheader. For sortable/filterable columns, useDataTableColumnHeader,DataTableColumnTitle, andDataTableColumnSortMenu(and column filter menus as needed). - meta for filter config:
label,placeholder,variant(text,select,multi_select,range,date,date_range,number,boolean),options(static{ label, value }[]),autoOptions(generate from data),unit(e.g."$"for range),showCounts,dynamicCounts,mergeStrategy("preserve"|"augment"|"replace"for options). SetenableColumnFilter: truewhen using column filters.
Filtering
Toolbar filters (inside DataTableToolbarSection)
- Global search:
DataTableSearchFilter— single search input; no column meta required. - Advanced (rule-based):
DataTableFilterMenu— command-palette style; add multiple filter rules with AND/OR. Columnmeta.variant(e.g.text,select,range,date) determines filter type. Install@niko-table/data-table-filter-menuand optionallycheckboxfrom Shadcn for multi-select. - Faceted (inline):
DataTableFacetedFilter— one filter per column; shows options with counts. UseaccessorKeyto tie to a column; options come from columnmeta.optionsormeta.autoOptions. Usemultiplefor multi-select.limitToFilteredRowsrestricts options to current result set. - Other toolbar:
DataTableSliderFilter,DataTableDateFilterfor range/date in toolbar;DataTableClearFilterto clear all filters.
Column-level filter menus (in header)
Render inside the column header next to DataTableColumnTitle and DataTableColumnSortMenu:
- Faceted:
DataTableColumnFacetedFilterMenu— select/multi-select with counts. Column needsmeta.optionsormeta.autoOptions; optionalmeta.showCounts,meta.dynamicCounts,meta.mergeStrategy. UseFILTER_VARIANTS.TEXT(or.NUMBER,.DATE) onDataTableColumnSortMenuwhen needed. - Slider (range):
DataTableColumnSliderFilterMenu— numeric range; columnmeta.variant: "range", optionalmeta.unit. - Date:
DataTableColumnDateFilterMenu— date or date-range; columnmeta.variant: "date"or"date_range".
Example column with faceted + sort:
import { DataTableColumnHeader, DataTableColumnTitle } from "@/components/niko-table/components/data-table-column-header"
import { DataTableColumnSortMenu } from "@/components/niko-table/components/data-table-column-sort"
import { DataTableColumnFacetedFilterMenu } from "@/components/niko-table/components/data-table-column-faceted-filter"
import { FILTER_VARIANTS } from "@/components/niko-table/lib/constants"
{
accessorKey: "category",
header: () => (
<DataTableColumnHeader>
<DataTableColumnTitle />
<DataTableColumnSortMenu variant={FILTER_VARIANTS.TEXT} />
<DataTableColumnFacetedFilterMenu multiple limitToFilteredRows={false} />
</DataTableColumnHeader>
),
meta: {
label: "Category",
options: categoryOptions,
mergeStrategy: "augment",
dynamicCounts: true,
showCounts: true,
},
enableColumnFilter: true,
}
Example toolbar with search + faceted + advanced + clear:
<DataTableToolbarSection>
<DataTableSearchFilter placeholder="Search..." />
<DataTableFacetedFilter accessorKey="category" title="Category" options={categoryOptions} multiple />
<DataTableFacetedFilter accessorKey="brand" limitToFilteredRows />
<DataTableFilterMenu autoOptions dynamicCounts showCounts mergeStrategy="augment" />
<DataTableViewMenu />
<DataTableClearFilter />
</DataTableToolbarSection>
Add-ons: data-table-search-filter, data-table-filter-menu, data-table-faceted-filter, data-table-clear-filter, data-table-slider-filter, data-table-date-filter, data-table-column-faceted-filter, data-table-column-slider-filter, data-table-column-date-filter. Full list at niko-table.com.
DataTableRoot Config and State
Most config is auto-detected from the components you render: e.g. DataTablePagination enables pagination, DataTableSearchFilter / DataTableFilterMenu / DataTableFacetedFilter / column filter menus enable filtering, DataTableColumnHeader / DataTableColumnSortMenu enable sorting, DataTableSelectionBar enables row selection. You only need to pass config when overriding defaults or for features that aren’t declared by a child (e.g. server-side or manual modes).
- config (override when needed):
manualPagination,manualSorting,manualFiltering,pageCount,initialPageSize,initialPageIndex,autoResetPageIndex,autoResetExpanded, or to turn off a feature. Full list:enablePagination,enableSorting,enableFilters,enableRowSelection,enableExpanding, etc. - state: Optional controlled
stateplusonPaginationChange,onSortingChange,onColumnFiltersChange,onColumnVisibilityChange,onRowSelectionChange,onExpandedChange,onRowSelection. - getRowId: Optional
(row, index) => string. Use stable unique IDs (e.g.(row) => row.id) when using row DnD, row selection, or expansion — default index-based IDs break after reorder. - Loading: Set
isLoadingonDataTableRoot; renderDataTableSkeletonandDataTableEmptyBodyinsideDataTableBody.
URL state (nuqs)
Sync table state (pagination, sorting, filters, search) with the URL for shareable, bookmarkable views. Use nuqs: install nuqs and wrap the app with the framework-specific NuqsAdapter in the app root (nuqs/adapters/next/app, nuqs/adapters/next/pages, or nuqs/adapters/react). See nuqs adapters docs for setup.
- Parsers: Define parsers with
parseAsInteger.withDefault(0)forpageIndex/pageSize,parseAsJsonforsort/filters,parseAsStringforsearch. Match TanStack Table state shape so URL params map 1:1 tostate. - Wiring:
useQueryStates(parsers, { history: "replace" })→[urlParams, setUrlParams]. Derivepagination,sorting,columnFilters,globalFilterfromurlParams(e.g. viauseMemo). Pass toDataTableRootasstate={{ pagination, sorting, columnFilters, globalFilter }}. InonPaginationChange,onSortingChange,onColumnFiltersChange,onGlobalFilterChange, callsetUrlParamswith the updated slice so the URL stays in sync. - DataTableFilterMenu: When using the filter menu with nuqs, filters in the URL are often stored as extended filter objects; convert between TanStack
ColumnFiltersStateand that shape in the handlers usingserializeFiltersForUrl/normalizeFiltersFromUrl(exported fromfilters/table-filter-menu— they strip/regeneratefilterIdto keep URLs short and input focus stable). See Advanced Nuqs Table and Server-Side Nuqs Table examples at niko-table.com.
Installation (for projects without Niko Table)
- Prerequisites: React project, Shadcn UI, TailwindCSS, TypeScript.
- Client components: Table components use React state and hooks; add
"use client"at the top of any file that rendersDataTableRootor Niko Table components (required in Next.js App Router and similar). - Registry: In
components.json, add:"registries": { "@niko-table": "https://niko-table.com/r/{name}.json" } - Core:
shadcn@latest add @niko-table/data-table(pullsdata-table-core+data-table-ui+ Root/chrome; installs/updatescomponents/ui/table.tsxwithTableComponentand a keyboard-focusable scroll container). For controls-only / own TanStack instance: install the control items — they resolvedata-table-corewithout Root ortable.tsx. Add@niko-table/data-table-uionly if you need our table primitive. - Add-ons (examples):
@niko-table/data-table-pagination,@niko-table/data-table-search-filter,@niko-table/data-table-view-menu,@niko-table/data-table-sort-menu,@niko-table/data-table-filter-menu, plus column-level filter/sort components as needed. Match names from the registry at niko-table.com. - Server-side: For
manualPagination/manualSorting/manualFiltering, setconfig.pageCount(e.g.Math.ceil(totalCount / pageSize)) and passtotalCounttoDataTablePaginationwhen using server-driven data.
Drag and Drop
- Row DnD: Do not combine with sorting or filtering (data order conflicts). Requires
getRowId={(row) => row.id}(or similar stable ID) — index-based IDs break after reorder. Wrap withDataTableRowDndProvideroutside<DataTable>(DnD context uses divs that cannot live inside<table>). UseDataTableDndBodyandDataTableRowDragHandleinside. Add a drag-handle column withcell: ({ row }) => <DataTableRowDragHandle rowId={row.id} />. - Column DnD: Safe to combine with other features. Use
DataTableColumnDndProvider,DataTableDraggableHeader,DataTableDragAlongCell, and the corresponding core structure components (including virtualized variants when needed).
Styling
Use semantic color tokens (e.g. bg-success, text-destructive) instead of hardcoded Tailwind colors.
Pitfalls to Avoid
- No barrel imports: Do not import from
@/components/niko-tableor.../coreor.../componentswithout the full path to the file (e.g..../core/data-table-root). - Row DnD without getRowId: Row drag-and-drop requires stable row IDs; pass
getRowId={(row) => row.id}(or your ID field). Omitting it or using index causes wrong behavior after reorder. - Row DnD with sorting/filtering: Do not enable row reorder and sort/filter together; data order becomes ambiguous.
- DataTableRowDndProvider inside <table>: The provider must wrap the whole
DataTablefrom outside; its markup cannot go inside<table>.
Minimal Table Template
"use client"
import { DataTableRoot } from "@/components/niko-table/core/data-table-root"
import { DataTable } from "@/components/niko-table/core/data-table"
import {
DataTableHeader,
DataTableBody,
DataTableSkeleton,
DataTableEmptyBody,
} from "@/components/niko-table/core/data-table-structure"
import { DataTableToolbarSection } from "@/components/niko-table/components/data-table-toolbar-section"
import { DataTableSearchFilter } from "@/components/niko-table/components/data-table-search-filter"
import { DataTablePagination } from "@/components/niko-table/components/data-table-pagination"
import type { DataTableColumnDef } from "@/components/niko-table/types"
type User = { id: string; name: string; email: string }
const columns: DataTableColumnDef<User>[] = [
{ accessorKey: "name", header: "Name" },
{ accessorKey: "email", header: "Email" },
]
export function UsersTable({ data, isLoading }: { data: User[]; isLoading?: boolean }) {
return (
<DataTableRoot data={data} columns={columns} isLoading={isLoading}>
<DataTableToolbarSection>
<DataTableSearchFilter placeholder="Search..." />
</DataTableToolbarSection>
<DataTable>
<DataTableHeader />
<DataTableBody>
<DataTableSkeleton />
<DataTableEmptyBody />
</DataTableBody>
</DataTable>
<DataTablePagination />
</DataTableRoot>
)
}
Data Grid
Editable spreadsheet-style grid built on the same DataTableRoot / virtualized body. Do not invent a separate widget API.
DataTableRoot data={grid.rows} getRowId={(r) => r.id}
→ DataGrid grid={grid}
→ opt-in: DataGridClipboard, DataGridFillHandle, DataGridMove, …
→ DataTable → VirtualizedHeader + VirtualizedBody (fixed height)
- Engine:
useDataGrid({ columnIds, createEmptyRow, initialRows? })— uncontrolled rows, focus/selection by{ rowId, columnId }, undo/redo. - Cells: Wrap editors in
<DataGridCell row={…} columnId={…}>. UseGridTextCell,GridNumberCell,GridCheckboxCell,GridDateCell,GridSelectCell/GridComboboxCell. Validity comes from yourresolve→CellState. - Opt-in features: Mount as children of
<DataGrid>only — unmounted = tree-shaken. - Persistence: Separate install
@niko-table/data-table-grid-changes→useGridChanges(grid, { initialRows }). - Server-side grid: no pagination — stream rows on scroll via
DataTableVirtualizedBody'sonNearEnd+prefetchThreshold. Load each chunk withgrid.updateRows(() => rows, { history: false })+changes.reset(rows), merging aroundchanges.dirtyRowIdsso unsaved edits survive. Save viachanges.getChangeSet()→ POST{ created, updated, deleted }→changes.reconcile({ succeededIds, failedIds }); failed rows stay dirty (highlight withfailedRowIds). RaiseuseDataGrid'smaxRows(default 200) above the expected loaded count. See Server-Side Grid example. - Docs: https://niko-table.com/data-grid/introduction/ · https://niko-table.com/examples/basic-grid/
Where to Learn More
- Online: https://niko-table.com — installation, examples, component overview, API. Table examples: Simple / Basic / Faceted / Advanced / Nuqs / Server-Side / Server-Side Nuqs / Infinite Scroll / Row DnD / Column DnD / Virtualization / Aside; the Drizzle ORM guide (with a live mocked demo that shows the generated SQL) implements the server-side wire contract. Data Grid examples: Basic Grid, Cell Types, Validation, Dynamic Columns, Persistence, Server Side. For resilience: DataTableErrorBoundary (core/data-table-error-boundary).
- Skills (AI): https://niko-table.com/getting-started/skills/ — how to install and use this skill.
- Docs guidelines: https://niko-table.com/contributing/documentation-guidelines/
- In-repo (when working in niko-table-registry):
src/content/docs/— e.g.getting-started/installation.mdx,niko-table/overview/,data-grid/overview/,examples/*-table.mdx,examples/*-grid.mdx.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/semkoo/niko-table-registry/niko-table-best-practices">View niko-table-best-practices on skillZs</a>