Segmented Filter

Segmented Filter picks one slice of a collection that is already on screen, and may show a count beside each label. Selection applies immediately. It is a radiogroup, not tabs — a filtered single list has no tabpanel. On a list page, pass it through Query List segmentedFilter so it mounts in the toolbar tabs slot and replaces a status-enum KPI band.

When To Use

• The choices are mutually exclusive, one is always active, and they slice the same collection (same object type, same columns).
• Selection should apply immediately, with no Save step.
• A list page's primary move is switching a status or lifecycle enum with counts — use Query List segmentedFilter instead of a clickable Statistic band.
• Keep two to five segments. Labels are nouns in sentence case (Failed, not Show failed).

When Not To Use

• Multi-select, or one dimension among several — put counts on filter values inside Query Filter.
• Distinct content areas or object types — use real tabs with panels.
• Initiating an action — use a Button.
• Highlighting a figure — use Statistic, and never make the figure clickable.

Features

Installing

pnpm dlx shadcn@latest add https://ui.isaacfei.com/r/segmented-filter.json

npx shadcn@latest add https://ui.isaacfei.com/r/segmented-filter.json

yarn dlx shadcn@latest add https://ui.isaacfei.com/r/segmented-filter.json

bun x shadcn@latest add https://ui.isaacfei.com/r/segmented-filter.json

With a namespace: npx shadcn@latest add @f-ui/segmented-filter.

registryDependencies: utils, shadcn toggle-group.

Usage

import { SegmentedFilter } from "@/components/f-ui/segmented-filter/segmented-filter";

<SegmentedFilter
  value={status}
  onValueChange={setStatus}
  aria-label="Filter by status"
  segments={[
    { value: "all", label: "All", count: 24 },
    { value: "pending", label: "Pending", count: 6 },
    { value: "ready", label: "Ready", count: 16 },
    { value: "failed", label: "Failed", count: 2 },
  ]}
/>

On a resource index, prefer the Query List config so the kit owns param writes and drops a duplicate Query Filter field:

<QueryList
  schema={schema}
  listCode="orders"
  adapter={adapter}
  params={params}
  onParamsChange={onParamsChange}
  getRowId={(row) => row.id}
  segmentedFilter={{
    paramKey: "status",
    label: "Filter by status",
    segments: [
      { value: "all", label: "All", count: totals.all },
      { value: "pending", label: "Pending", count: totals.pending },
      { value: "ready", label: "Ready", count: totals.ready },
      { value: "failed", label: "Failed", count: totals.failed },
    ],
  }}
/>

allValue defaults to "all". Selecting that segment clears params[paramKey] with null and resets page to 1. Do not also expose the same paramKey as a Query Filter field — the kit drops any matching field so there is one owner per param.

Examples

Status Filter

A four-segment status strip with facet counts. Click a slice — the selection stays on one value; the counts sit beside the labels as muted tabular figures.

"use client";

import { useState } from "react";

import { SegmentedFilter } from "@/components/f-ui/segmented-filter/segmented-filter";

const segments = [
  { value: "all", label: "All", count: 24 },
  { value: "pending", label: "Pending", count: 6 },
  { value: "ready", label: "Ready", count: 16 },
  { value: "failed", label: "Failed", count: 2 },
];

export function SegmentedFilterDemo() {
  const [value, setValue] = useState("all");
  return (
    <SegmentedFilter
      value={value}
      onValueChange={setValue}
      segments={segments}
      aria-label="Filter by status"
    />
  );
}

Composition

SegmentedFilter (radiogroup)
└── segment × n (radio)
    ├── label
    └── count? (muted tabular-nums)

Accessibility

The root is a radiogroup, and each segment is a radio. A tab must own a tabpanel; a filtered single list has none, so this control must not ship role="tab".

aria-label is required. The radios are otherwise an unlabelled group. Hosts localize that name (Filter by status, Filter by severity).

API Reference

Props

SegmentedFilter

SegmentedFilterSegment