Introduction

FilterCN is a headless, URL-driven conditional filter component built on top of shadcn/ui for Next.js. It lets your users build complex, multi-field queries (like a "where clause" builder) that are automatically serialized to URL search parameters — perfect for server-side filtering with REST APIs.

Features

URL-driven state — All filter state lives in the URL, making filters shareable and bookmarkable
Zero backend changes — Works with any existing REST API endpoint
Type-safe fields — Supports string, number, boolean, date, and select field types
Auto-detects your project — The CLI finds your src/ layout and tsconfig.json alias automatically
Fully extensible — Bring your own operators, custom param builders, and locales

Quick Start

Install in seconds with the CLI:

pnpm dlx filtercn init

Then wrap your page with FilterProvider:

tsx

import { FilterProvider, FilterBar } from "@/components/conditional-filter";

const fields = [
  { name: "status", label: "Status", type: "select", options: [...] },
  { name: "price",  label: "Price",  type: "number" },
];

export default function DataPage() {
  return (
    <div className="p-8">
      <h1>My Products</h1>
      
      {/* 2. Wrap your application with the context provider and render the Bar */}
      <FilterProvider config={{ fields, paramStyle: "underscore" }}>
        <FilterBar searchPlaceholder="Filter products..." />
      </FilterProvider>
      
      {/* ... your data table reading from URL Search Params ... */}
    </div>
  );
}

Introduction

Features

Quick Start

Built With