Keyframery

Filter

The faceted filter of a data table's toolbar: a dashed chip that opens a searchable list of values with counts, built on UI SDK's combobox. Chosen values arrive in the chip as badges one after another while the chip widens around them on a spring, counts roll, and a bar of filters slides its Reset in while any is active.

See it as an AI agent does.

Resize preview. Focus the handle and use the left or right arrow keys. Hold Shift for larger steps.— px
Customize1 controls
Animation speed1×

Installation

npx shadcn@latest add @keyframery/filter

This adds components/keyframery/filter.tsx and its primitive to your project, and installs UI SDK, along with combobox, badge, which it builds on. The motion tokens are added to your global CSS the first time you install a component.

Usage

import { Filter } from "@/components/keyframery/filter"

export default function Usage() {
  return (
    <Filter
      label="Status"
      options={[
        { value: "paid", label: "Paid", count: 12 },
        { value: "pending", label: "Pending", count: 4 },
      ]}
    />
  )
}

Examples

A filter with counts

Each option shows how many rows have it. Chosen values appear in the chip as badges; past two they read "3 selected".

A bar of filters, controlled

The value is always a list of strings. Reset slides in while any filter in the bar is active and clears them all.

One value at a time

With multiple={false} choosing a value replaces the last one and closes the list. The value is still a list, of one.

Motion

MoveWhat you see
UnfoldThe list grows out of its chip, its rows cascade in, and one highlight glides between them.
DrawA chosen option's box fills with a pop and its check draws itself.
WidenThe chip's width follows its badges on a spring, so it never stretches its text.
CascadeBadges pop in one after another, from a smaller, blurred start.
Roll"3 selected" and every option's count roll to their new number.
SlideThe bar's Reset slides in from the left while a filter is active, and out again.

Timing and springiness follow the motion style you set. To change how fast this filter moves, pass speed:

<Filter speed="fast">
  …
</Filter>

"fast" is 0.6×, "slow" 1.4×, and a number sets the multiplier. With reduced motion turned on, nothing moves: changes happen at once or with a short fade.

Theming

Set these CSS variables on the component or a parent. Leave them unset to follow the light and dark theme. The open Customize panel below the preview lets you try these settings.

VariableWhat it changesDefault
--filter-faceThe chip while open, and the list's sheet--popover
--filter-inkThe chip's label and the options--foreground
--filter-borderThe chip's dashed outline--border
--filter-accentA chosen option's box--primary
--filter-badgeThe chosen values' badges--secondary
--filter-radiusThe chip's corners9px
--filter-heightThe chip's height2rem
--filter-list-widthThe list's width15rem

API reference

Every part takes className and children, along with the props of the element it renders. The parts are rendered by UI SDK, so they also take render, to draw your own element, and a function of their state for className and style.

Filter

Renders a <div>, and takes its props too.

Prop

Type

FilterBar

Renders a <div>, and takes its props too.

Prop

Type

FilterClear

Renders a <div>, and takes its props too.

Prop

Type

FilterContent

Renders a <div>, and takes its props too.

Prop

Type

FilterOption

Renders a <div>, and takes its props too.

Prop

Type

FilterOptionIndicator

Renders a <span>, and takes its props too.

Prop

Type

FilterValues

Renders a <span>, and takes its props too.

Prop

Type

Other parts

These take the props of the element they render, and nothing else:

  • FilterBarReset: a <button>
  • FilterEmpty: a <div>
  • FilterInput: a <input>
  • FilterList: a <div>
  • FilterSeparator: a <div>
  • FilterTrigger: a <button>

Keyboard

KeyWhat it does
Enter / SpaceOn the chip: opens the list with focus in its search field.
TypeNarrows the options.
ArrowDown / ArrowUpMoves the highlight, wrapping at the ends.
Home / EndHighlights the first or last row (End reaches Clear filter).
EnterChooses or unchooses the highlighted option, or clears the filter on Clear filter.
BackspaceIn the empty search field: removes the last chosen value.
EscapeCloses the list and returns focus to the chip.

Accessibility

Roles, keyboard and focus are declared on the component's UI SDK primitive, and state is announced through the matching ARIA attributes. More in Accessibility.

Built on UI SDK's core

UI SDK doesn't ship a filter, so this one is defined with its core: one definePrimitive in components/keyframery/core/filter-core.ts, with no React in it. UI SDK's adapters can render that same definition in Vue, Svelte, Solid and web components. To keep your own styling and take only the motion, import from @/components/keyframery/primitives/filter.

Questions

How does the animated Filter for UI SDK move?

Unfold: The list grows out of its chip, its rows cascade in, and one highlight glides between them. Draw: A chosen option's box fills with a pop and its check draws itself. Widen: The chip's width follows its badges on a spring, so it never stretches its text. Cascade: Badges pop in one after another, from a smaller, blurred start. Roll: "3 selected" and every option's count roll to their new number. Slide: The bar's Reset slides in from the left while a filter is active, and out again.

Do I need Motion or Framer Motion for the animated Filter?

No. Every move is plain CSS, so there is nothing to install besides the component and UI SDK.

UI SDK has no filter. How is this one built on UI SDK?

Its behaviour is one definition written with UI SDK's core (definePrimitive), in components/keyframery/core/filter-core.ts. Its parts are rendered by UI SDK's adapter, so they take render, state-based class names and data-slot, like every UI SDK component.

What happens to the Filter when someone turns on reduced motion?

Nothing moves. State changes happen at once, or with a short fade.

All components

On this page