Faceted Filter Table

Add inline faceted filters that show available options and counts.

Product Name	Category	Brand	Price	Stock	Rating	In Stock	Release Date
iPhone 15 Pro	Electronics	apple	$999.00	45	5★	Yes	2/2/2026
Galaxy S24 Ultra	Electronics	samsung	$1199.00	32	5★	Yes	1/28/2026
Air Jordan 1	Sports	nike	$170.00	8	4★	Yes	1/13/2026
Ultraboost 23	Sports	adidas	$190.00	15	4★	Yes	12/19/2025
PlayStation 5	Electronics	sony	$499.00	0	5★	No	2/7/2025
OLED C3 TV	Electronics	lg	$1499.00	12	5★	Yes	11/9/2025
XPS 15 Laptop	Electronics	dell	$1899.00	20	4★	Yes	10/10/2025
Spectre x360	Electronics	hp	$1599.00	18	4★	Yes	1/23/2026
MacBook Pro 16	Electronics	apple	$2499.00	25	5★	Yes	1/8/2026
Galaxy Book3	Electronics	samsung	$1399.00	14	4★	Yes	8/11/2025

Preview with Controlled State

Open in

Product Name	Category	Brand	Price	Stock	Rating	In Stock	Release Date
iPhone 15 Pro	Electronics	apple	$999.00	45	5★	Yes	2/2/2026
Galaxy S24 Ultra	Electronics	samsung	$1199.00	32	5★	Yes	1/28/2026
Air Jordan 1	Sports	nike	$170.00	8	4★	Yes	1/13/2026
Ultraboost 23	Sports	adidas	$190.00	15	4★	Yes	12/19/2025
PlayStation 5	Electronics	sony	$499.00	0	5★	No	2/7/2025
OLED C3 TV	Electronics	lg	$1499.00	12	5★	Yes	11/9/2025
XPS 15 Laptop	Electronics	dell	$1899.00	20	4★	Yes	10/10/2025
Spectre x360	Electronics	hp	$1599.00	18	4★	Yes	1/23/2026
MacBook Pro 16	Electronics	apple	$2499.00	25	5★	Yes	1/8/2026
Galaxy Book3	Electronics	samsung	$1399.00	14	4★	Yes	8/11/2025

Current Table State

Live view of the current table state for demonstration purposes

Search Query:None

Total Items:15

Active Filters:0

Sorting:None

Page:1 (Size: 10)

Hidden Columns:0

Pinned Columns:0 Left, 0 Right

View Full State Object

Column Filters:

[]

Sorting:

[]

Column Visibility:

{}

Column Pinning:

{
  "left": [],
  "right": []
}

Introduction

The Faceted Filter Table adds inline filter components that show available options with counts. Users can quickly see what filters are available and how many items match each option.

Installation

Add the required components:

npx shadcn@latest add table input button dropdown-menu popover command badge scroll-area separator

Add tanstack/react-table dependency:

npm install @tanstack/react-table

Copy the DataTable components into your project. See the Installation Guide for detailed instructions.

Prerequisites

We are going to build a table to show products with faceted filters. Here’s what our data looks like:

1
type Product = {
2
  id: string
3
  name: string
4
  category: string
5
  brand: string
6
  price: number
7
  stock: number
8
  rating: number
9
  inStock: boolean
10
  releaseDate: Date
11
}
12

13
const categoryOptions = [
14
  { label: "Electronics", value: "electronics" },
15
  { label: "Clothing", value: "clothing" },
16
  { label: "Sports", value: "sports" },
17
]

Basic Table with Faceted Filters

Let’s start by building a table with faceted filters.

Column Definitions

First, we’ll define our columns with filter functions.

1
"use client"
2

3
import {
4
  DataTableColumnHeader,
5
  DataTableColumnTitle,
6
  DataTableColumnSortMenu,
7
  DataTableColumnFacetedFilterMenu,
8
  DataTableColumnSliderFilterMenu,
9
  DataTableColumnDateFilterMenu,
10
} from "@/components/niko-table/components"
11
import { FILTER_VARIANTS } from "@/components/niko-table/lib"
12
import type { DataTableColumnDef } from "@/components/niko-table/types"
13

14
export type Product = {
15
  id: string
16
  name: string
17
  category: string
18
  brand: string
19
  price: number
20
  stock: number
21
  rating: number
22
  inStock: boolean
23
  releaseDate: Date
24
}
25

26
export const columns: DataTableColumnDef<Product>[] = [
27
  {
28
    accessorKey: "name",
29
    header: () => (
30
      <DataTableColumnHeader>
31
        <DataTableColumnTitle />
32
        <DataTableColumnSortMenu />
33
      </DataTableColumnHeader>
34
    ),
35
    meta: { label: "Product Name" },
36
  },
37
  {
38
    accessorKey: "category",
39
    header: () => (
40
      <DataTableColumnHeader>
41
        <DataTableColumnTitle />
42
        <DataTableColumnSortMenu variant={FILTER_VARIANTS.TEXT} />
43
        <DataTableColumnFacetedFilterMenu
44
          multiple
45
          limitToFilteredRows={false}
46
        />
47
      </DataTableColumnHeader>
48
    ),
49
    meta: {
50
      label: "Category",
51
      options: categoryOptions,
52
      mergeStrategy: "augment",
53
      dynamicCounts: true,
54
      showCounts: true,
55
    },
56
    enableColumnFilter: true,
57
  },
58
  {
59
    accessorKey: "brand",
60
    header: () => (
61
      <DataTableColumnHeader>
62
        <DataTableColumnTitle />
63
        <DataTableColumnSortMenu variant={FILTER_VARIANTS.TEXT} />
64
        <DataTableColumnFacetedFilterMenu limitToFilteredRows />
65
      </DataTableColumnHeader>
66
    ),
67
    meta: {
68
      label: "Brand",
69
      autoOptions: true,
70
      dynamicCounts: true,
71
      showCounts: true,
72
    },
73
    enableColumnFilter: true,
74
  },
75
  {
76
    accessorKey: "price",
77
    header: () => (
78
      <DataTableColumnHeader>
79
        <DataTableColumnTitle />
80
        <DataTableColumnSortMenu variant={FILTER_VARIANTS.NUMBER} />
81
        <DataTableColumnSliderFilterMenu />
82
      </DataTableColumnHeader>
83
    ),
84
    meta: {
85
      label: "Price",
86
      unit: "$",
87
      variant: "range", // Auto-applies numberRangeFilter
88
    },
89
    enableColumnFilter: true,
90
  },
91
  {
92
    accessorKey: "releaseDate",
93
    header: () => (
94
      <DataTableColumnHeader>
95
        <DataTableColumnTitle />
96
        <DataTableColumnSortMenu />
97
        <DataTableColumnDateFilterMenu />
98
      </DataTableColumnHeader>
99
    ),
100
    meta: {
101
      label: "Release Date",
102
      variant: "date_range", // Auto-applies dateRangeFilter
103
    },
104
    enableColumnFilter: true,
105
  },
106
]

`<DataTable />` component

Next, we’ll add faceted filter components.

1
"use client"
2

3
import {
4
  DataTableRoot,
5
  DataTable,
6
  DataTableHeader,
7
  DataTableBody,
8
  DataTableEmptyBody,
9
} from "@/components/niko-table/core"
10
import {
11
  DataTableToolbarSection,
12
  DataTablePagination,
13
  DataTableSearchFilter,
14
  DataTableViewMenu,
15
  DataTableFacetedFilter,
16
  DataTableSliderFilter,
17
  DataTableDateFilter,
18
  DataTableClearFilter,
19
  DataTableColumnHeader,
20
  DataTableColumnTitle,
21
  DataTableColumnSortMenu,
22
  DataTableColumnFacetedFilterMenu,
23
  DataTableColumnSliderFilterMenu,
24
  DataTableColumnDateFilterMenu,
25
} from "@/components/niko-table/components"
26
import { FILTER_VARIANTS } from "@/components/niko-table/lib"
27
import type { DataTableColumnDef } from "@/components/niko-table/types"
28

29
type Product = {
30
  id: string
31
  name: string
32
  category: string
33
  brand: string
34
  price: number
35
  stock: number
36
  rating: number
37
  inStock: boolean
38
  releaseDate: Date
39
}
40

41
const categoryOptions = [
42
  { label: "Electronics", value: "electronics" },
43
  { label: "Clothing", value: "clothing" },
44
  { label: "Sports", value: "sports" },
45
]
46

47
const columns: DataTableColumnDef<Product>[] = [
48
  {
49
    accessorKey: "name",
50
    header: () => (
51
      <DataTableColumnHeader>
52
        <DataTableColumnTitle />
53
        <DataTableColumnSortMenu />
54
      </DataTableColumnHeader>
55
    ),
56
    meta: { label: "Product Name" },
57
  },
58
  {
59
    accessorKey: "category",
60
    header: () => (
61
      <DataTableColumnHeader>
62
        <DataTableColumnTitle />
63
        <DataTableColumnSortMenu variant={FILTER_VARIANTS.TEXT} />
64
        <DataTableColumnFacetedFilterMenu
65
          multiple
66
          limitToFilteredRows={false}
67
        />
68
      </DataTableColumnHeader>
69
    ),
70
    meta: {
71
      label: "Category",
72
      options: categoryOptions,
73
      mergeStrategy: "augment",
74
      dynamicCounts: true,
75
      showCounts: true,
76
    },
77
    enableColumnFilter: true,
78
  },
79
  {
80
    accessorKey: "brand",
81
    header: () => (
82
      <DataTableColumnHeader>
83
        <DataTableColumnTitle />
84
        <DataTableColumnSortMenu variant={FILTER_VARIANTS.TEXT} />
85
        <DataTableColumnFacetedFilterMenu limitToFilteredRows />
86
      </DataTableColumnHeader>
87
    ),
88
    meta: {
89
      label: "Brand",
90
      autoOptions: true,
91
      dynamicCounts: true,
92
      showCounts: true,
93
    },
94
    enableColumnFilter: true,
95
  },
96
  {
97
    accessorKey: "price",
98
    header: () => (
99
      <DataTableColumnHeader>
100
        <DataTableColumnTitle />
101
        <DataTableColumnSortMenu variant={FILTER_VARIANTS.NUMBER} />
102
        <DataTableColumnSliderFilterMenu />
103
      </DataTableColumnHeader>
104
    ),
105
    meta: {
106
      label: "Price",
107
      unit: "$",
108
      variant: "range",
109
    },
110
    enableColumnFilter: true,
111
  },
112
  {
113
    accessorKey: "releaseDate",
114
    header: () => (
115
      <DataTableColumnHeader>
116
        <DataTableColumnTitle />
117
        <DataTableColumnSortMenu />
118
        <DataTableColumnDateFilterMenu />
119
      </DataTableColumnHeader>
120
    ),
121
    meta: {
122
      label: "Release Date",
123
      variant: "date_range",
124
    },
125
    enableColumnFilter: true,
126
  },
127
]
128

129
export function FacetedFilterTable({ data }: { data: Product[] }) {
130
  return (
131
    <DataTableRoot data={data} columns={columns}>
132
      <DataTableToolbarSection className="w-full flex-col justify-between gap-2">
133
        <DataTableToolbarSection className="px-0">
134
          <DataTableSearchFilter placeholder="Search products..." />
135
          <DataTableViewMenu />
136
        </DataTableToolbarSection>
137
        <DataTableToolbarSection className="flex-wrap px-0">
138
          {/* Category: show all options (not limited by other filters) */}
139
          <DataTableFacetedFilter
140
            accessorKey="category"
141
            multiple
142
            limitToFilteredRows={false}
143
          />
144
          {/* Brand: show only brands from filtered rows */}
145
          <DataTableFacetedFilter accessorKey="brand" limitToFilteredRows />
146
          <DataTableSliderFilter accessorKey="price" />
147
          <DataTableDateFilter accessorKey="releaseDate" multiple />
148
          <DataTableClearFilter />
149
        </DataTableToolbarSection>
150
      </DataTableToolbarSection>
151

152
      <DataTable>
153
        <DataTableHeader />
154
        <DataTableBody>
155
          <DataTableEmptyBody />
156
        </DataTableBody>
157
      </DataTable>
158

159
      <DataTablePagination />
160
    </DataTableRoot>
161
  )
162
}

Faceted Filter Component

DataTableFacetedFilter

The faceted filter component shows available options with counts.

Props:

Name	Type	Default	Description
`accessorKey`	`keyof TData & string`	-	The column key to filter (required)
`title`	`string`	-	Optional override (defaults to column meta.label or accessor name)
`options`	`Option[]`	-	Static options; if omitted and column meta allows, options are auto-generated
`multiple`	`boolean`	-	Allow multiple selections (defaults based on column variant)
`showCounts`	`boolean`	`true`	Show counts next to options
`dynamicCounts`	`boolean`	`true`	Counts reflect filtered rows
`limitToFilteredRows`	`boolean`	`true`	Show only options from filtered rows (vs all rows)

limitToFilteredRows

The limitToFilteredRows prop controls whether the filter shows options from all data or only from the currently filtered rows.

When limitToFilteredRows={true} (default):

Options are generated from rows that match other active filters
Useful for filters like “Brand” or “Rating” where you want to see only relevant options
Example: If you filter by “Category: Electronics”, the Brand filter will only show brands that exist in Electronics

When limitToFilteredRows={false}:

Options are generated from all rows, regardless of other filters
Useful for filters like “Category” where you want to see all available categories
Example: Category filter always shows all categories, even when other filters are active

1
// Category: Show all options (not limited by other filters)
2
<DataTableFacetedFilter
3
  accessorKey="category"
4
  title="Category"
5
  options={categoryOptions}
6
  multiple
7
  limitToFilteredRows={false} // Always show all categories
8
/>
9

10
// Brand: Show only brands from filtered rows
11
<DataTableFacetedFilter
12
  accessorKey="brand"
13
  title="Brand"
14
  multiple
15
  limitToFilteredRows={true} // Only show brands from current filter results
16
/>

1
// Auto-generated when meta.autoOptions or meta.options are set appropriately
2
<DataTableFacetedFilter accessorKey="category" multiple />

DataTableClearFilter

Button to clear all active filters.

1
<DataTableClearFilter />

Filter Functions

Note: For most use cases, you don’t need to define custom filterFn. The default extendedFilter handles the ExtendedColumnFilter format automatically. Only define a custom filterFn if you need special filtering logic.

If you do define a custom filterFn, it will work as you define it:

1
{
2
  accessorKey: "category",
3
  enableColumnFilter: true,
4
  // Custom filter function (optional - default works for most cases)
5
  filterFn: (row, id, filterValue: string[]) => {
6
    if (!filterValue?.length) return true
7
    const rowValue = String(row.getValue(id))
8
    return filterValue.includes(rowValue)
9
  },
10
}

Auto-applied filter functions:

When you specify meta.variant in your column definition, the appropriate filterFn is automatically applied:

variant: "range" → numberRangeFilter (for numeric ranges like price)
variant: "date" or variant: "date_range" → dateRangeFilter (for date filtering)

1
{
2
  accessorKey: "price",
3
  meta: {
4
    label: "Price",
5
    variant: "range", // Auto-applies numberRangeFilter
6
    unit: "$",
7
  },
8
  // No need to define filterFn - it's auto-applied!
9
}

Multiple Selection

Enable multiple selections with the multiple prop:

1
<DataTableFacetedFilter
2
  accessorKey="category"
3
  title="Category"
4
  options={categoryOptions}
5
  multiple // Allow selecting multiple categories
6
/>

Controlled State

Manage filter state externally for full control:

1
import { useState } from "react"
2
import type {
3
  PaginationState,
4
  SortingState,
5
  ColumnFiltersState,
6
  VisibilityState,
7
} from "@tanstack/react-table"
8

9
export function ControlledFacetedFilterTable({ data }: { data: Product[] }) {
10
  const [globalFilter, setGlobalFilter] = useState<string | object>("")
11
  const [sorting, setSorting] = useState<SortingState>([])
12
  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])
13
  const [columnVisibility, setColumnVisibility] = useState<VisibilityState>({})
14
  const [pagination, setPagination] = useState<PaginationState>({
15
    pageIndex: 0,
16
    pageSize: 10,
17
  })
18

19
  return (
20
    <DataTableRoot
21
      data={data}
22
      columns={columns}
23
      state={{
24
        globalFilter,
25
        sorting,
26
        columnFilters,
27
        columnVisibility,
28
        pagination,
29
      }}
30
      onGlobalFilterChange={value => {
31
        setGlobalFilter(value)
32
        setPagination(prev => ({ ...prev, pageIndex: 0 }))
33
      }}
34
      onSortingChange={setSorting}
35
      onColumnFiltersChange={filters => {
36
        setColumnFilters(filters)
37
        setPagination(prev => ({ ...prev, pageIndex: 0 }))
38
      }}
39
      onColumnVisibilityChange={setColumnVisibility}
40
      onPaginationChange={setPagination}
41
    >
42
      <DataTableToolbarSection className="w-full flex-col justify-between gap-2">
43
        <DataTableToolbarSection className="px-0">
44
          <DataTableSearchFilter placeholder="Search products..." />
45
          <DataTableViewMenu />
46
        </DataTableToolbarSection>
47
        <DataTableToolbarSection className="flex-wrap px-0">
48
          <DataTableFacetedFilter
49
            accessorKey="category"
50
            multiple
51
            limitToFilteredRows={false}
52
          />
53
          <DataTableFacetedFilter accessorKey="brand" limitToFilteredRows />
54
          <DataTableSliderFilter accessorKey="price" />
55
          <DataTableDateFilter accessorKey="releaseDate" multiple />
56
          <DataTableClearFilter />
57
        </DataTableToolbarSection>
58
      </DataTableToolbarSection>
59

60
      <DataTable>
61
        <DataTableHeader />
62
        <DataTableBody>
63
          <DataTableEmptyBody />
64
        </DataTableBody>
65
      </DataTable>
66

67
      <DataTablePagination />
68
    </DataTableRoot>
69
  )
70
}

When to Use

✅ Use Faceted Filter Table when:

You have categorical data (categories, tags, statuses)
Users need to see available options and counts
You want inline, visible filters
Multiple filter options are common

❌ Consider other options when:

You need complex rule-based filtering (use Advanced Table)
You prefer dropdown filters (use Advanced Table)
You only need search (use Search Table)

Next Steps

Advanced Table - Add advanced filtering menus
Search Table - Add global search

Faceted Filter Table

Introduction

Installation

Prerequisites

Basic Table with Faceted Filters

Column Definitions

`<DataTable />` component

Faceted Filter Component

DataTableFacetedFilter

limitToFilteredRows

DataTableClearFilter

Filter Functions

Multiple Selection

Controlled State

When to Use

Next Steps

Getting Started

Niko Table

Examples

Contributing

Faceted Filter Table

Introduction

Installation

Prerequisites

Basic Table with Faceted Filters

Column Definitions

<DataTable /> component

Faceted Filter Component

DataTableFacetedFilter

limitToFilteredRows

DataTableClearFilter

Filter Functions

Multiple Selection

Controlled State

When to Use

Next Steps

Getting Started

Niko Table

Examples

Contributing

`<DataTable />` component