Usage Examples

Learn how to integrate the conditional filter component into your pages step-by-step.

Live Preview

Try the filter component right here — click Filters to open the panel and add conditions:

Step 1: Define Your Fields

Start by defining the fields users can filter on. Define the array outside your component to prevent unnecessary re-renders.

tsx

import type { FilterFieldDefinition } from "@/components/conditional-filter/types";

const myFields: FilterFieldDefinition[] = [
  { 
    name: "status", 
    label: "Status", 
    type: "select", 
    options: [
      { label: "Active", value: "active" },
      { label: "Draft",  value: "draft"  },
    ],
  },
  { name: "name",       label: "Name",       type: "text"   },
  { name: "price",      label: "Price",      type: "number" },
  { name: "created_at", label: "Created At", type: "date"   },
];

Step 2: Wrap with Provider and Render

Use FilterProvider to inject config, then render FilterBar (which includes the FilterRoot popover and a global search input).

tsx

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

export default function ProductsPage() {
  return (
    <div className="p-8 max-w-4xl mx-auto">
      <FilterProvider config={{ fields: myFields, paramStyle: "underscore" }}>
        <FilterBar searchPlaceholder="Search products..." />
      </FilterProvider>
    </div>
  );
}

Step 3: Read URL State on the Server

Once users apply filters, the provider serializes them to URL search params automatically. Read them in any server component or API route:

tsx

export default async function ProductsPage({
  searchParams,
}: {
  searchParams: Record<string, string>;
}) {
  // e.g. { status: "active", price__gt: "100" }
  const products = await fetch(`/api/products?${new URLSearchParams(searchParams)}`);
  // ...
}

Step 4: Extract the API query parameters (Client)

Access the parsed query parameters directly from any client component inside the provider via the useFilterQuery hook:

tsx

"use client";
import { useFilterQuery } from "@/components/conditional-filter";

export function ActiveFiltersCount() {
  const { queryParams, activeCount } = useFilterQuery();
  
  // Example queryParams: { status__in: "active,draft", price__gte: 100 }
  return <span>{activeCount} active filter(s)</span>;
}