Bruno DelorenceBruno
Appearance
Appearance

Choose your reading theme.

Contact

Filter builder

New

A table’s Filters popover with nested groups: conditions joined by an And/Or pill, subgroups in tinted panels, values fitted to each field, and rows you drag between groups.

filter-builder/filter-builder.tsx
Live · interactive

Opportunities

NameAmountCompanyStageHealth score
Harbor Expansion$ 180,000OstraTechnical winCritical
Atlas Rollout$ 180,000BrightmoorTechnical winCritical
Beacon Platform Upgrade$ 137,500BrightmoorRequirementsCritical
Cedar Line Renewal$ 220,000BrightmoorRequirementsAt risk
Driftwood Pilot$ 124,000Corvid LabsRequirementsCritical
Ember Analytics Suite$ 137,500Corvid LabsRequirementsHealthy
Fjord Data Migration$ 180,000Halden & CoRequirementsCritical
Granite Seat Expansion$ 60,000Halden & CoTechnical winCritical
8 of 18Sum $ 1,219,000

The live component, numbered part by part. Every measurement is read from it as it is drawn. Point at a row to outline its part, or at a part to find its row.

The choices it offers, each value drawn live and the default marked, with how to pick one.

When to use

  • A table of records people narrow with questions that mix all and any: the owner is me, and the deal is critical or has no meeting booked.
  • Saved views a team returns to, each a tab with its own conditions, where the count on the Filters button says at a glance how narrowed a view is.
  • Fields of different kinds in one place: people, statuses, stages, amounts and dates, each with the operators and values that make sense for it.
  • Power users who build a filter once and rearrange it later: dragging a condition into a subgroup is quicker than deleting and adding it again.

When not to use

  • One or two simple filters. Use filter chips in the toolbar; a popover of nested groups is more than a status and an owner need.
  • Free-text search across records. Use a search field; conditions test known fields with known values.
  • Queries people type or share as text. Use a query editor with completion; this builds the tree with pointer and keyboard.
  • Deep logic. The popover nests two levels of subgroups; anything deeper reads better as a saved segment with a name.

How conditions combine

  • One conjunction per group: every row in a group is joined by the same And or Or, and its pill flips them all at once.
  • A subgroup is one part of the group around it: “Owner is Imani, and any of these three”. New subgroups start with Or, the usual reason to make one.
  • Two levels deep: the top group, its subgroups and theirs. The deepest ones offer no Add subgroup.
  • Unfinished parts are left out: a condition without a value and an empty group test nothing, so adding a row never empties the table by surprise.

Views and the count

Each tab keeps its own conditions, and switching tabs keeps your edits to the others. The badge on Filters counts the conditions that have a value, so a glance tells how narrowed the view is; with none, it goes. onFilterChange hands over the filter and the rows that pass it, to save the view or fetch from a server.

Each one drawn with the component itself, used well or badly.

The fields, operators and captions come with the component; the words you supply are the title, the view names and the records.

  • Title: the records the table holds, plural: Opportunities, Accounts.
  • View names: two or three words saying what the view shows, in sentence case: Best case, This quarter, My deals. No “View” or “Filter” in the name.
  • People and companies: names are cut short with an ellipsis in the value, so the part that tells them apart goes first.
  • At most six views: + Add stops at six, and more tabs than that crowd the row on a phone.

You can add this component with the shadcn CLI or by hand:

Into components/filter-builder of any React project, with no setup:

Terminal
npx shadcn@latest add https://brunodelorence.com/r/filter-builder.json

Either way it needs React 19 and a bundler that supports CSS Modules, such as Next.js or Vite. It has a dark colour scheme: it follows your page’s color-scheme, light unless the page sets one, or its colorScheme prop, with nothing to configure. Browsers without light-dark() show it light.

Usage

pipeline.tsx
import { FilterBuilder, type Group } from './filter-builder';const mine: Group = {  type: 'group',  id: 'root',  conj: 'and',  items: [    { type: 'condition', id: 'owner', field: 'owner', op: 'is', value: ['imani'] },    { type: 'condition', id: 'stage', field: 'stage', op: 'anyOf', value: ['proposal'] },  ],};export function Pipeline() {  return (    <FilterBuilder      views={[{ id: 'mine', label: 'My deals', filter: mine }]}      onFilterChange={(filter, rows) => console.log(filter, rows.length)}      autoplay={false}    />  );}

Each state below is a live instance, locked so you can study it.

The pieces it is built from, each with its measurements read live.

Below are variations of this component, each live, with its code.

Stalled deals

A view joined by Or: no recent interaction, no meeting booked, or a large deal at risk, the last as an And subgroup.

Grouped by stage

The Best case view in compact rows, grouped by stage with each group’s count and sum; Company hidden, Owner and Next meeting shown.

Picking stages

This quarter’s filter open on the Stage value: a multi-select listbox of pills with two ticked.

No matches

One person’s view whose conditions leave nothing, with grid lines: the empty state offers Edit filters and Clear filters.

A sales team’s Opportunities table and the popover that narrows it. Each condition is a row: a handle, a field, an operator that fits the field (is, is any of, when, before, is over) and a value picked from a list that fits too: a person with their initials, a health status with its coloured square, a date preset, several stages as pills that fold into +1. The rows of a group are joined on a bracket by one pill, And or Or, that flips the group when pressed; a subgroup sits in a tinted panel with its own pill, Add condition and Add subgroup. Rows move by their handle, within a group or into another, and the table behind filters as you go, with the count on the Filters button and an empty state. View tabs keep a filter each; the toolbar groups, hides fields, sets the row height and the lines. Light and dark.

  • The filter is a tree: a group holds conditions and subgroups and one conjunction. A row passes a group when all (And) or any (Or) of its parts pass; a condition without a value and a group with nothing in it are left out, so a new row changes nothing until it has a value.
  • Each field has a kind (person, status, stage, company, amount, date) and each kind its operators. Changing the field resets the operator and value; changing the operator keeps the values that still fit, so is any of keeps every stage and is keeps the first.
  • Dates are days from today. when tests a range (No meeting, This week, Next week, This month); before and after compare with a day (Today, In 7 days, 7 days ago), so the table reads the same whenever it opens.
  • The value is a listbox fitted to the field: initials on the owner’s colour, a square in the status colour, stages as their pills, companies with their drawn marks. is any of keeps the list open while you tick; the row shows the first value and +1 for the rest.
  • Dragging a handle lifts the row and measures every slot in reading order, a subgroup’s own between its parent’s; an accent line shows the nearest one, and letting go moves the row there. ↑ and ↓ on a focused handle step through the same slots, into and out of subgroups.
  • Whatever changes the tree, the rows that moved glide from where they were (FLIP on the separate translate property) and new rows grow in; the conjunction’s glyph turns half a circle and its word rolls, and so does the badge’s count.
  • Under 440 px of popover the bracket gives way to the pill between the rows, and each condition puts the field over the operator and value. The table scrolls inside its box with the name held at the left.
  • While on screen and untouched, a demo pointer opens Filters, flips And to Or and back, adds a condition to the subgroup and picks its value, then drags Stage into the subgroup. Any real input hands it over; it comes back after 8 s of quiet.
PropTypeDefaultDescription
titlestring'Opportunities'The table’s name, beside its icon.
opportunitiesOpportunity[]eighteen dealsThe rows: name, amount, company, stage, health, owner, days to the next meeting and days since the last interaction (null for none).
peoplePerson[]five peopleEveryone who can own a deal: an id, a name and a colour for their initials.
companiesCompany[]six companiesThe companies the deals are with: an id, a name, a mark shape and its colour.
viewsSavedView[]All opportunities, Best case, This quarterThe view tabs, each an id, a label and its filter (a Group).
defaultViewstring—The tab open at first; the first one when left out.
defaultStateFilterBuilderState—Opens locked in a moment, with the demo off: the view, the popover open, a filter in place of the view’s, a picker or menu held open, the grouping, row height, lines, hidden columns, or a row held mid-drag.
onFilterChange(filter: Group, rows: Opportunity[]) => void—Called with the view’s filter and the rows that pass it whenever the filter changes.
onViewChange(id: string) => void—Called with a view’s id when its tab is chosen or added.
autoplaybooleantrueWhile on screen and untouched, a demo pointer shows the main interactions. Any real input stops it.
colorScheme'light' | 'dark' | 'system'—Light or dark colours, or the reader’s; without it, the page’s color-scheme.
classNamestring—Classes for the stage.

Keyboard

  • The view tabs are a tablist: ← and → move between them and choose, Home and End jump to the ends.
  • Filters opens the popover and moves the focus into it; Escape closes it and gives the focus back to Filters.
  • In a field, operator or value list, ↑ and ↓ move, Home and End jump, Enter or Space picks, Escape closes and returns to the trigger. Tab closes the list.
  • ↑ and ↓ on a row’s handle move the row one slot at a time, into and out of subgroups, and the handle keeps the focus.
  • Enter or Space on a handle opens its menu, Move up and Move down; the arrows move between them and Escape closes it.

Screen readers

  • Filters is named with its count, “Filters, 5 conditions”, since the badge itself is hidden.
  • Each change is announced with the rows left, through a status region (WCAG 4.1.3, AA): “Removed Owner is Imani Okafor”, then how many opportunities show.
  • The pill is named by what it does, “Joined by And; switch to Or”, and each subgroup is a group labelled by its caption.
  • Handles are named “Move Stage condition” with where the row is, describe the arrow keys, and say they open a menu (aria-haspopup, aria-expanded).

Dragging

Dragging has a keyboard way (2.1.1, A) and a single-pointer one (Dragging Movements, 2.5.7, AA): a click on the handle opens Move up and Move down, which take the same one-slot steps as the arrow keys. An item that can’t go further is disabled.

Contrast

Text is at least 4.5:1 on the surface it sits on in both schemes (1.4.3, AA), the quiet grey of placeholders, counts and the handle included; the handle and the bins are at least 3:1 (1.4.11, AA). The health squares sit beside their names, so the colour is never the only cue.

Targets and motion

Every control is at least 24 px across (2.5.8, AA): the handle narrows to 24 px wide on a phone, the rest are 28 px or more. With reduced motion, rows jump to their places instead of gliding, and the demo pointer stays off.

In this build

  • The Filters button opens a non-modal dialog (aria-haspopup="dialog", aria-expanded) and its label counts the conditions; Escape closes it with the focus back on the button, and a press outside closes it too.
  • Field, operator and value are buttons that open a listbox; the arrows, Home and End move through the options, Enter or Space picks, and a multi-value listbox is aria-multiselectable and stays open. Escape closes it with the focus back on its button.
  • Each conjunction pill says what it does: “Joined by And; switch to Or”. A subgroup is a group named by its caption. Every bin names the condition it removes.
  • A row’s handle is a button: ↑ and ↓ move the row one slot at a time, into and out of subgroups, and the live region says where it landed (“Stage moved: 1 of 4 in the subgroup”), as it says every change and how many rows remain.
  • The views are a tablist moved with the arrow keys; Groups, Group by, Fields, Row height and Layout are menu buttons with radio and checkbox items. The table has column headers, each name is its row’s header, and grouped rows sit in a tbody per group with a disclosure button.
  • Under reduced motion nothing slides, rolls or grows and the demo never plays. The demo pointer is decorative.

The complete source behind this demo. Open source under the MIT license, © 2026 Bruno Delorence: copy it, change it, ship it.

filter-builder.tsx
// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import {  Fragment,  useCallback,  useEffect,  useEffectEvent,  useId,  useLayoutEffect,  useMemo,  useRef,  useState,  type KeyboardEvent as ReactKeyboardEvent,  type ReactNode,} from 'react';import { Avatar, CompanyMark, HealthChip, HealthSquare, StagePill } from './cells';import {  COMPANIES,  HEALTH,  OPPORTUNITIES,  PEOPLE,  STAGES,
panel.tsx
// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import {  Fragment,  useEffect,  useLayoutEffect,  useRef,  useState,  type KeyboardEvent as ReactKeyboardEvent,  type PointerEvent as ReactPointerEvent,  type Ref,} from 'react';import { Avatar, CompanyMark, HealthSquare, StagePill } from './cells';import type { Company, HealthId, Person, StageId } from './data';import {  FIELDS,  OP_LABEL,  depthOf,  describe,  freshCondition,  locate,  moveItem,
filter.ts
// Copyright (c) 2026 Bruno Delorence. MIT License.import {  COMPANIES,  HEALTH,  PEOPLE,  STAGES,  money,  type Company,  type Opportunity,  type Person,} from './data';/* * The filter as data: a group of conditions and subgroups joined by And or Or, the fields a * condition can test, the operators each kind of field takes, the values each offers, and the * pure functions that test a row and rearrange the tree. Nothing here draws. */export type FieldId =  'owner' | 'health' | 'stage' | 'company' | 'amount' | 'nextMeeting' | 'lastInteraction';export type OpId =  'is' | 'isNot' | 'anyOf' | 'noneOf' | 'over' | 'under' | 'when' | 'before' | 'after';export type Conj = 'and' | 'or';
popup.tsx
// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import {  useEffect,  useLayoutEffect,  useRef,  useState,  type KeyboardEvent as ReactKeyboardEvent,  type ReactNode,} from 'react';import { Icon } from './glyphs';import styles from './filter-builder.module.css';/* * The small popups: a listbox for a condition's field, operator or value, and a menu for the * toolbar's buttons. Both sit on the stage under their trigger (over it when there is no room * below), in the stage's own px, since a gallery card may scale the whole stage. The arrows, Home * and End move between items; Escape closes and gives the focus back; a press elsewhere closes. * A multi-select listbox stays open while you tick. */const ITEMS =
cells.tsx
// Copyright (c) 2026 Bruno Delorence. MIT License.import type { Company, HealthId, Person, StageId } from './data';import { HEALTH, STAGES } from './data';import styles from './filter-builder.module.css';/* * The small pieces the table and the value pickers share: a person's initials on their tint, a * company's mark, a stage pill and a health chip. */export function Avatar({ person, size = 20 }: { person: Person; size?: number }) {  const initials = person.name    .split(' ')    .map((part) => part[0])    .slice(0, 2)    .join('');  return (    <span      className={styles.avatar}      style={{ width: size, height: size, background: person.tint, fontSize: size * 0.42 }}      aria-hidden="true"      data-part="avatar"    >
filter-builder.module.css
/* Filter builder (filter-builder.tsx): a CRM's Opportunities table on a grey stage, white by day   and near-black by night. The card holds the page head, the view tabs, the toolbar and the   table; the Filters popover opens over the table, under its button, and the pickers open over   both, on the stage.   Under 560 px of popover a condition's value takes a second line; under 640 px of card the   toolbar keeps only Filters' label and scrolls sideways, and the table scrolls inside its box.   Colours are the tokens below, light-dark(light, dark) where the two differ: the component takes   the color-scheme it inherits from the page, or the one its colorScheme prop sets   (data-color-scheme). */.root {  --stage: #eef0f3;  --card: #ffffff;  --card-edge: #e3e5e9;  --line: #eceef1;  --ink: #1c1d21;  --ink-2: #61646d;  --ink-3: #686b73;  --hover: #f3f4f6;  --hover-strong: #eef0f3;  --field: #ffffff;  --field-edge: #e2e4e8;
data.ts
// Copyright (c) 2026 Bruno Delorence. MIT License.import type { Group } from './filter';/* * The sample a sales team's Opportunities table holds: people who own deals, the companies they * sell to, the stages a deal moves through and the deals themselves. Dates are days from today, * so the table reads the same whenever it opens. */export type Person = { id: string; name: string; tint: string };export type CompanyMarkShape = 'ring' | 'tile' | 'chevron' | 'bars' | 'diamond' | 'peak';export type Company = { id: string; name: string; mark: CompanyMarkShape; tint: string };export type StageId = 'discovery' | 'requirements' | 'technical' | 'proposal' | 'negotiation';export type HealthId = 'critical' | 'risk' | 'healthy';export type Opportunity = {  id: string;  name: string;  amount: number;  company: string;  stage: StageId;  health: HealthId;  owner: string;
glyphs.tsx
// Copyright (c) 2026 Bruno Delorence. MIT License./* * The interface's line icons: a 24-unit box, drawn with currentColor. */const PATHS = {  plus: 'M12 5v14M5 12h14',  chevronDown: 'M7.5 10l4.5 4.5 4.5-4.5',  trash:    'M4.5 6.5h15M9.5 6.5V4.8c0-.7.5-1.2 1.2-1.2h2.6c.7 0 1.2.5 1.2 1.2v1.7M6.5 6.5l.8 12.2c.1.9.8 1.6 1.7 1.6h6c.9 0 1.6-.7 1.7-1.6l.8-12.2M10.2 10.5v6M13.8 10.5v6',  swap: 'M18.5 9.5A7 7 0 0 0 6 7.6M5.5 4v4h4M5.5 14.5A7 7 0 0 0 18 16.4M18.5 20v-4h-4',  groups: 'M4 7h9M4 12h6M4 17h9M15 9.5l3.5 2.5-3.5 2.5',  filter: 'M4.5 7h15M7.5 12h9M10.5 17h3',  groupBy: 'M4.5 5h15v14h-15zM8 9.5h8M8 14.5h5',  fields: 'M3.8 9.3 9 4.5h10.7v10.7l-5.2 5.2H3.8zM14.2 9.8h.01',  rowHeight: 'M9.5 6h10M9.5 12h10M9.5 18h10M4.5 4.5v3M4.5 10.5v3M4.5 16.5v3',  layout: 'M4 5.5h16v13H4zM4 10.5h16',  check: 'M5 12.5l4.5 4.5L19 7.5',  close: 'M7 7l10 10M17 7 7 17',  funnelOff: 'M4.5 5.5h15l-5.8 7.2v5.6l-3.4 1.8v-7.4z',  chevronRight: 'M10 7.5l4.5 4.5-4.5 4.5',} as const;
demo-pointer.tsx
// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import type { CSSProperties, Ref } from 'react';/* * The demo's pointer, and the steps that move it. A demo is a script of awaited steps: wait, or * glide the pointer somewhere. Stopping the demo (the reader takes over, or it scrolls away) ends * the step in progress at once: its promise rejects, which ends the script right there, and the * pointer fades out. * * Each glide is a curved flight played by the Web Animations API, so nothing runs frame by frame. * The points of the flight are handed to whoever wants to move along with it. The arrow and the * hand are HTML boxes * that swap by their visibility: a change of style inside an SVG would lay the SVG out again. */export type Point = { x: number; y: number };/** A glide's path and timing, for an animation that plays along with it. */export type Flight = { points: Point[]; timing: KeyframeAnimationOptions };export type Demo = {
use-autoplay.ts
// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import { useCallback, useEffect, useRef, useState } from 'react';/* * When a demo may play on its own: while part of it is on screen and the tab is visible, never * under reduced motion, and not while the reader is using it. `take()` hands it to the reader; it * takes back over `idle` ms after their last input. */export function useAutoplay<T extends HTMLElement>(idle = 6000) {  const ref = useRef<T>(null);  const [visible, setVisible] = useState(false);  const [reduced, setReduced] = useState(true);  const [taken, setTaken] = useState(false);  const timer = useRef(0);  useEffect(() => {    const element = ref.current;    if (!element) return;    let onScreen = false;    const update = () => setVisible(onScreen && !document.hidden);    const observer = new IntersectionObserver(