UI / Core

FilterBar

Controlled filter controls with per-item single- and multi-select modes.

1"use client";2 3import { useState } from "react";4import { FilterBar, formatConditionLabel, type FilterBarItem } from "@cardspark/ui/core";5 6const conditionOptions = [7  { value: "All Conditions", label: "All Conditions", compactLabel: "All" },8  ...["Near Mint", "Lightly Played", "Moderately Played", "Damaged"].map((condition) => ({9    value: condition,10    label: formatConditionLabel(condition, "code-label"),11    compactLabel: formatConditionLabel(condition, "code")12  }))13];14const filterOptions = [15  { id: "source", label: "Source", multiple: true, values: ["All Sources"], options: ["All Sources", "TCGplayer", "eBay", "Shopify"] },16  { id: "grader", label: "Grader", value: "Ungraded", options: ["Ungraded", "PSA", "CGC", "BGS", "TAG"] },17  { id: "condition", label: "Condition", multiple: true, values: ["Lightly Played"], options: conditionOptions, compact: true },18  { id: "variant", label: "Variant", multiple: true, values: ["Holofoil", "Reverse Holofoil"], options: ["All Variants", "Normal", "Holofoil", "Reverse Holofoil", "First Edition"] },19  { id: "rarity", label: "Rarity", multiple: true, values: ["All Rarities"], options: ["All Rarities", "Rare", "Rare Holo", "Illustration Rare", "Special Illustration Rare", "Hyper Rare"] }20] satisfies FilterBarItem[];21const sortOptions = ["Most valuable", "Least valuable", "Newest", "Oldest"];22 23export function FilterBarDemo() {24  const [filters, setFilters] = useState(filterOptions);25  const [sort, setSort] = useState(sortOptions[0]);26 27  return (28    <FilterBar29      filters={filters}30      actions={31        <label className="cs-filter-control" htmlFor="card-sort">32          <span className="cs-filter-label">Sort</span>33          <span className="cs-filter-select">34            <span className="cs-filter-size-probe" aria-hidden="true">35              {sort}36            </span>37            <select id="card-sort" name="sort" value={sort} aria-label="Sort" onChange={(event) => setSort(event.target.value)}>38              {sortOptions.map((option) => (39                <option key={option} value={option}>40                  {option}41                </option>42              ))}43            </select>44            <span className="cs-filter-caret" aria-hidden="true">▼</span>45          </span>46        </label>47      }48      onChange={(id, selection) => {49        setFilters((current) => current.map((filter) => {50          if (filter.id !== id) return filter;51 52          return filter.multiple53            ? { ...filter, values: Array.isArray(selection) ? selection : [selection] }54            : { ...filter, value: Array.isArray(selection) ? selection[0] ?? filter.value : selection };55        }));56      }}57    />58  );59}

Installation

Install the package.

npm install @cardspark/ui

Import the shared stylesheet layer near your app root.

app/layout.tsx

1import "@cardspark/ui/tokens.css";2import "@cardspark/ui/themes/basement.css";3import "@cardspark/ui/styles.css";

Import and render FilterBar from its package entry point.

FilterBarDemo.tsx

1"use client";2 3import { useState } from "react";4import { FilterBar, formatConditionLabel, type FilterBarItem } from "@cardspark/ui/core";5 6const conditionOptions = [7  { value: "All Conditions", label: "All Conditions", compactLabel: "All" },8  ...["Near Mint", "Lightly Played", "Moderately Played", "Damaged"].map((condition) => ({9    value: condition,10    label: formatConditionLabel(condition, "code-label"),11    compactLabel: formatConditionLabel(condition, "code")12  }))13];14const filterOptions = [15  { id: "source", label: "Source", multiple: true, values: ["All Sources"], options: ["All Sources", "TCGplayer", "eBay", "Shopify"] },16  { id: "grader", label: "Grader", value: "Ungraded", options: ["Ungraded", "PSA", "CGC", "BGS", "TAG"] },17  { id: "condition", label: "Condition", multiple: true, values: ["Lightly Played"], options: conditionOptions, compact: true },18  { id: "variant", label: "Variant", multiple: true, values: ["Holofoil", "Reverse Holofoil"], options: ["All Variants", "Normal", "Holofoil", "Reverse Holofoil", "First Edition"] },19  { id: "rarity", label: "Rarity", multiple: true, values: ["All Rarities"], options: ["All Rarities", "Rare", "Rare Holo", "Illustration Rare", "Special Illustration Rare", "Hyper Rare"] }20] satisfies FilterBarItem[];21const sortOptions = ["Most valuable", "Least valuable", "Newest", "Oldest"];22 23export function FilterBarDemo() {24  const [filters, setFilters] = useState(filterOptions);25  const [sort, setSort] = useState(sortOptions[0]);26 27  return (28    <FilterBar29      filters={filters}30      actions={31        <label className="cs-filter-control" htmlFor="card-sort">32          <span className="cs-filter-label">Sort</span>33          <span className="cs-filter-select">34            <span className="cs-filter-size-probe" aria-hidden="true">35              {sort}36            </span>37            <select id="card-sort" name="sort" value={sort} aria-label="Sort" onChange={(event) => setSort(event.target.value)}>38              {sortOptions.map((option) => (39                <option key={option} value={option}>40                  {option}41                </option>42              ))}43            </select>44            <span className="cs-filter-caret" aria-hidden="true">▼</span>45          </span>46        </label>47      }48      onChange={(id, selection) => {49        setFilters((current) => current.map((filter) => {50          if (filter.id !== id) return filter;51 52          return filter.multiple53            ? { ...filter, values: Array.isArray(selection) ? selection : [selection] }54            : { ...filter, value: Array.isArray(selection) ? selection[0] ?? filter.value : selection };55        }));56      }}57    />58  );59}

Usage

FilterBarDemo.tsx

1"use client";2 3import { useState } from "react";4import { FilterBar, formatConditionLabel, type FilterBarItem } from "@cardspark/ui/core";5 6const conditionOptions = [7  { value: "All Conditions", label: "All Conditions", compactLabel: "All" },8  ...["Near Mint", "Lightly Played", "Moderately Played", "Damaged"].map((condition) => ({9    value: condition,10    label: formatConditionLabel(condition, "code-label"),11    compactLabel: formatConditionLabel(condition, "code")12  }))13];14const filterOptions = [15  { id: "source", label: "Source", multiple: true, values: ["All Sources"], options: ["All Sources", "TCGplayer", "eBay", "Shopify"] },16  { id: "grader", label: "Grader", value: "Ungraded", options: ["Ungraded", "PSA", "CGC", "BGS", "TAG"] },17  { id: "condition", label: "Condition", multiple: true, values: ["Lightly Played"], options: conditionOptions, compact: true },18  { id: "variant", label: "Variant", multiple: true, values: ["Holofoil", "Reverse Holofoil"], options: ["All Variants", "Normal", "Holofoil", "Reverse Holofoil", "First Edition"] },19  { id: "rarity", label: "Rarity", multiple: true, values: ["All Rarities"], options: ["All Rarities", "Rare", "Rare Holo", "Illustration Rare", "Special Illustration Rare", "Hyper Rare"] }20] satisfies FilterBarItem[];21const sortOptions = ["Most valuable", "Least valuable", "Newest", "Oldest"];22 23export function FilterBarDemo() {24  const [filters, setFilters] = useState(filterOptions);25  const [sort, setSort] = useState(sortOptions[0]);26 27  return (28    <FilterBar29      filters={filters}30      actions={31        <label className="cs-filter-control" htmlFor="card-sort">32          <span className="cs-filter-label">Sort</span>33          <span className="cs-filter-select">34            <span className="cs-filter-size-probe" aria-hidden="true">35              {sort}36            </span>37            <select id="card-sort" name="sort" value={sort} aria-label="Sort" onChange={(event) => setSort(event.target.value)}>38              {sortOptions.map((option) => (39                <option key={option} value={option}>40                  {option}41                </option>42              ))}43            </select>44            <span className="cs-filter-caret" aria-hidden="true">▼</span>45          </span>46        </label>47      }48      onChange={(id, selection) => {49        setFilters((current) => current.map((filter) => {50          if (filter.id !== id) return filter;51 52          return filter.multiple53            ? { ...filter, values: Array.isArray(selection) ? selection : [selection] }54            : { ...filter, value: Array.isArray(selection) ? selection[0] ?? filter.value : selection };55        }));56      }}57    />58  );59}

Composition

Use FilterBar as the control strip around a data-owning surface; keep the actual filtering and sorting state in the parent.

1FilterableSurface2├── Header / result count3├── FilterBar4│   ├── filter definitions5│   ├── selected values6│   └── optional actions7└── Results owned by the parent surface

FilterBar reports changes by filter id, while the surrounding surface filters data, handles loading states, and renders the resulting content.

Features

Renders filters as compact select and multi-select controls with shared package spacing and overflow behavior.
Uses each item's multiple discriminator to pair value with single-select items and values with multi-select items.
Reports both selection shapes through one onChange callback and forwards native section props and refs.

Examples

Multiselect states

Show all-value, single-value, multi-value, compact-label, and disabled-option multiselect states in the same control pattern.

All values

Selecting the all option returns the compact add-filter affordance.

All Sources

Single value

One selected value renders the selected option label directly in the trigger.

Multiple values

Multiple active values collapse to a count and expose clear behavior from the menu.

Compact labels

Compact options keep dense trading-card state readable in narrow rows.

Unavailable options

Disabled options remain visible in the menu while staying unavailable for selection.

In Stock

1"use client";2 3import { useState } from "react";4import { FilterBar, formatConditionLabel, type FilterBarItem } from "@cardspark/ui/core";5 6const multiselectStateExamples: Array<{ title: string; filters: FilterBarItem[] }> = [7  {8    title: "All values",9    filters: [10      {11        id: "source",12        label: "Source",13        multiple: true,14        values: ["All Sources"],15        options: ["All Sources", "TCGplayer", "eBay", "Shopify"]16      }17    ]18  },19  {20    title: "Single value",21    filters: [22      {23        id: "rarity",24        label: "Rarity",25        multiple: true,26        values: ["Rare Holo"],27        options: ["All Rarities", "Common", "Uncommon", "Rare", "Rare Holo", "Illustration Rare"]28      }29    ]30  },31  {32    title: "Multiple values",33    filters: [34      {35        id: "variant",36        label: "Variant",37        multiple: true,38        values: ["Holofoil", "Reverse Holofoil"],39        options: ["All Variants", "Normal", "Holofoil", "Reverse Holofoil", "First Edition"]40      }41    ]42  },43  {44    title: "Compact labels",45    filters: [46      {47        id: "condition",48        label: "Condition",49        multiple: true,50        values: ["Lightly Played"],51        options: [52          { value: "All Conditions", label: "All Conditions", compactLabel: "All" },53          ...["Near Mint", "Lightly Played", "Moderately Played", "Damaged"].map((condition) => ({54            value: condition,55            label: formatConditionLabel(condition, "code-label"),56            compactLabel: formatConditionLabel(condition, "code")57          }))58        ],59        compact: true60      }61    ]62  },63  {64    title: "Unavailable options",65    filters: [66      {67        id: "availability",68        label: "Availability",69        multiple: true,70        values: ["In Stock"],71        options: ["All Availability", "In Stock", { value: "Preorder", disabled: true }, "Sold"]72      }73    ]74  }75];76 77export function FilterBarMultiselectStates() {78  const [exampleFilters, setExampleFilters] = useState(multiselectStateExamples.map((example) => example.filters));79 80  function updateExampleFilter(exampleIndex, id, values) {81    setExampleFilters((currentExamples) =>82      currentExamples.map((filters, currentIndex) =>83        currentIndex === exampleIndex84          ? filters.map((filter) => filter.id === id && filter.multiple ? { ...filter, values } : filter)85          : filters86      )87    );88  }89 90  return (91    <div className="filter-bar-state-examples">92      {multiselectStateExamples.map((example, index) => (93        <section key={example.title}>94          <h3>{example.title}</h3>95          <FilterBar96            filters={exampleFilters[index]}97            onChange={(id, selection) => updateExampleFilter(98              index,99              id,100              Array.isArray(selection) ? selection : [selection]101            )}102          />103        </section>104      ))}105    </div>106  );107}

API Reference

Prop	Type	Default	Description
`filters`	`FilterBarItem[]`	-	Controlled filters. Single items use `value`; items with `multiple: true` use `values`.
`actions`	`ReactNode`	-	Optional trailing action content rendered inside the component.
`onChange`	`(id: string, selection: string \| string[]) => void`	-	Reports a controlled filter selection using the item's single or multi-select shape.
`ariaLabel`	`string`	`"Filters"`	Accessible label for the filter region.