FilterPlugin

Advanced column filtering with type-aware operators in a side panel

The FilterPlugin provides a side panel UI for building complex column filters with type-aware operators. It supports string, number, date, and enum filters with automatic operator selection based on column type.

Installation

npm install @izumisy/seizen-table-plugins

Import

import { FilterPlugin } from "@izumisy/seizen-table-plugins/filter";

Basic Usage

import { useSeizenTable, SeizenTable } from "@izumisy/seizen-table";
import { FilterPlugin } from "@izumisy/seizen-table-plugins/filter";

function UsersTable() {
  const table = useSeizenTable({
    data,
    columns,
    plugins: [FilterPlugin.configure({ width: 320 })],
  });

  return <SeizenTable table={table} />;
}

Configuration

width · number · default: "320"

Width of the filter side panel in pixels

disableGlobalSearch · boolean · default: "false"

Disable the global search input in the header slot

Defining Filterable Columns

To enable filtering on a column, add filterType to the column’s meta property:

import type { ColumnDef } from "@izumisy/seizen-table";

type Person = {
  name: string;
  age: number;
  status: string;
  joinedAt: string;
};

const columns: ColumnDef<Person>[] = [
  {
    accessorKey: "name",
    header: "Name",
    meta: { filterType: "string" },
  },
  {
    accessorKey: "age",
    header: "Age",
    meta: { filterType: "number" },
  },
  {
    accessorKey: "status",
    header: "Status",
    meta: {
      filterType: "enum",
      filterEnumValues: ["active", "inactive", "pending"],
    },
  },
  {
    accessorKey: "joinedAt",
    header: "Joined Date",
    meta: { filterType: "date" },
  },
];

Filter Types and Operators

String Filters

String Column

{
  accessorKey: "name",
  header: "Name",
  meta: { filterType: "string" },
}

Available Operators:

• Contains - Value contains the search term
• Equals - Exact match
• Starts with - Value starts with the search term
• Ends with - Value ends with the search term
• Is empty - Value is null or empty string
• Is not empty - Value is not null or empty string

Number Filters

Number Column

{
  accessorKey: "age",
  header: "Age",
  meta: { filterType: "number" },
}

Available Operators:

• = (equals)
• ≠ (not equals)
• > (greater than)
• ≥ (greater than or equal)
• < (less than)
• ≤ (less than or equal)

Date Filters

Date Column

{
  accessorKey: "createdAt",
  header: "Created",
  meta: { filterType: "date" },
}

Available Operators:

• = (on date)
• Before - Before the specified date
• After - After the specified date

Enum Filters

Enum Column

{
  accessorKey: "status",
  header: "Status",
  meta: {
    filterType: "enum",
    filterEnumValues: ["active", "inactive", "pending"],
  },
}

Available Operators:

• Is - Value matches the selection
• Is not - Value does not match the selection

Global Search

By default, FilterPlugin adds a global search input to the table header. This searches across all columns:

// Global search is enabled by default
FilterPlugin.configure({ width: 320 })

// Disable global search
FilterPlugin.configure({ 
  width: 320,
  disableGlobalSearch: true,
})

Programmatic Control

You can open and close the filter panel programmatically:

function MyTable() {
  const table = useSeizenTable({
    data,
    columns,
    plugins: [FilterPlugin.configure({ width: 320 })],
  });

  const openFilters = () => {
    table.plugin.open("filter");
  };

  const closeFilters = () => {
    table.plugin.close("filter");
  };

  return (
    <div>
      <button onClick={openFilters}>Open Filters</button>
      <SeizenTable table={table} />
    </div>
  );
}

Accessing Filter State

You can access the current filter state from the table instance:

const currentFilters = table.getFilterState();
console.log(currentFilters);

Subscribe to filter changes using the event bus:

import { useSeizenTableEvent } from "@izumisy/seizen-table";

useSeizenTableEvent(table, "filter-change", (filters) => {
  console.log("Filters changed:", filters);
});

Complete Example

Complete Example

import { useSeizenTable, SeizenTable, useSeizenTableEvent } from "@izumisy/seizen-table";
import { FilterPlugin } from "@izumisy/seizen-table-plugins/filter";
import type { ColumnDef } from "@izumisy/seizen-table";

type User = {
  id: number;
  name: string;
  email: string;
  age: number;
  status: "active" | "inactive" | "pending";
  joinedAt: string;
};

const columns: ColumnDef<User>[] = [
  {
    accessorKey: "name",
    header: "Name",
    meta: { filterType: "string" },
  },
  {
    accessorKey: "email",
    header: "Email",
    meta: { filterType: "string" },
  },
  {
    accessorKey: "age",
    header: "Age",
    meta: { filterType: "number" },
  },
  {
    accessorKey: "status",
    header: "Status",
    meta: {
      filterType: "enum",
      filterEnumValues: ["active", "inactive", "pending"],
    },
  },
  {
    accessorKey: "joinedAt",
    header: "Joined",
    meta: { filterType: "date" },
  },
];

function UsersTable({ users }: { users: User[] }) {
  const table = useSeizenTable({
    data: users,
    columns,
    plugins: [
      FilterPlugin.configure({
        width: 320,
        disableGlobalSearch: false,
      }),
    ],
  });

  // React to filter changes
  useSeizenTableEvent(table, "filter-change", (filters) => {
    console.log("Active filters:", filters);
  });

  return <SeizenTable table={table} />;
}