Faceted

Installation

pnpm dlx shadcn@latest add @diceui/faceted

Layout

Import the parts and compose them together.

import {
  Faceted,
  FacetedClear,
  FacetedContent,
  FacetedEmpty,
  FacetedGroup,
  FacetedInput,
  FacetedItem,
  FacetedItemIndicator,
  FacetedList,
  FacetedLoading,
  FacetedTrigger,
  FacetedValue,
} from "@/components/ui/faceted";
 
return (
  <Faceted>
    <FacetedTrigger>
      <FacetedValue />
    </FacetedTrigger>
    <FacetedContent>
      <FacetedInput />
      <FacetedList>
        <FacetedLoading />
        <FacetedEmpty />
        <FacetedGroup>
          <FacetedItem>
            <FacetedItemIndicator />
          </FacetedItem>
        </FacetedGroup>
        <FacetedClear />
      </FacetedList>
    </FacetedContent>
  </Faceted>
)

Examples

Multiple

Set multiple to select more than one value. FacetedItemIndicator can show a count until the item is selected, and FacetedClear appears once something is selected.

Groups

Split items into groups with headings, and separate them with FacetedSeparator.

Async

Search on the server by setting shouldFilter={false} on FacetedContent and controlling the search with value and onValueChange on FacetedInput. Show FacetedLoading while a request is pending. Keep the selected options in items so their badges stay labeled when they aren't in the current results.

Controlled

Control the selection with value and onValueChange.

API Reference

Faceted

The root component. It holds the selection and the popover's open state.

FacetedTrigger

The button that opens the popover. Use render to render your own button.

FacetedValue

Shows the current selection inside the trigger, as badges or a placeholder. Labels come from the items passed to Faceted.

FacetedBadgeList

The container for the selection badges.

FacetedBadge

A badge for one selected option.

FacetedContent

The popover content. It wraps its children in a command menu.

FacetedInput

The search input that filters the items.

FacetedList

The scrollable list of groups and items.

FacetedEmpty

Shown when no items match the search.

FacetedLoading

Shown while results are loading, such as during a server search.

FacetedGroup

A group of items with an optional heading.

FacetedItem

A selectable option.

FacetedItemIndicator

The check shown on selected items. Its children, such as a count, show while the item isn't selected.

FacetedClear

An item that clears the selection, in its own group below a separator. It only renders when something is selected.

FacetedSeparator

A line between groups.

Accessibility

Keyboard Interactions