This library is still in development and is available only for internal usage at VTEX.

Filter

Version: Next

Filter

Filter triggers allow merchants to find relevant information by choosing criteria and refining results.

Filters are built using combined components. There are components that allow the creation of simple filters, multiple selection filters, simple filters with search and multiple selection filters with search:

Component	Description
`FilterDisclosure`	Component for the buttons that trigger the menu.
`FilterPopover`	Popover component, which is always a parent component.
`FilterListbox`	Component for the option list.
`FilterFooter`	Component for the footer with clear and apply buttons.
`FilterOptionCheckbox`	Checkbox option component, this should be used only on multiple selection filters.
`FilterOptionRadio`	Radio option component, this should be used only on single selection filters.
`FilterSearchbox`	Search box component that should be used only when building searchable filters.
`FilterGroup`	A grouping component that displays the disclosures as cohesive bar.
`FilterControl`	A filter for toggling visibility of optional filters. Should be used when some of the filters are optional.
`FilterOptional`	Wrapper component that mounts and unmounts a filter, making it optional. Controlled by `FilterControl`.

Allows user to search and to select more than one option.

This section presents a series of examples that may be useful.

Filter supports internationalization of its native messages.

When fetching the option list asynchronously you just need to render your obtained list with a map. Providing values for id and label. You can control the status (loading/ready) with setStatus.

When performing searches asynchronously you need to render the search result list with a map. You can control the status with setStatus, to indicate the search is loading use the loading prop on FilterSearchbox.

import {
  FilterDisclosure,
  FilterPopover,
  FilterListbox,
  FilterOptionRadio,
  FilterOptionCheckbox,
  FilterFooter,
  useFilterMultipleState,
  useFilterState,
  useFilterGroupState,
  FilterGroup,
} from '@vtex/admin-ui'

function Example() {
  const filterState = useFilterState()
  const multipleSelectState = useFilterMultipleState()

  const filterGroupState = useFilterGroupState({
    filterStates: [state2, state],
  })

  return(
    <FilterGroup>
      // basic filter
      <FilterDisclosure state={filterState}>Example</FilterDisclosure>

      <FilterPopover state={filterState}>
        <FilterListbox>
          <FilterOptionRadio id="#1" label="Full" />
          <FilterOptionRadio id="#2" label="Empty" />
          <FilterOptionRadio id="#3" label="Half full" />
        </FilterListbox>
        <FilterFooter />
      </FilterPopover>

      // multiple selection filter
      <FilterDisclosure state={multipleSelectState}>Example</FilterDisclosure>

      <FilterPopover state={multipleSelectState}>
        <FilterListbox>
          <FilterOptionCheckbox id="#1" label="Full" />
          <FilterOptionCheckbox id="#2" label="Empty" />
          <FilterOptionCheckbox id="#3" label="Half full" />
        </FilterListbox>
        <FilterFooter />
      </FilterPopover>
    <FilterGroup />
  )
}

The state hooks useFilterState and useFilterMultipleState contain all business logic needed for controlling individual filters. The two hooks are different, but they share many props in common.

The state hook useFilterGroupState handles the "clear all" action for the FilterGroup component.

All filter states use the type FilterOption for the listed options. The type T used for value will affect the return type of all state that represents options.

Name	Type	Description	Required	Default
id	string	Unique id for this option.	✅	-
label	string	Label that will be rendered for the option.	✅	-
value	T (any object)	This is an optional value that can have any type. You can use it to manage additional data asssociated with the options.	🚫	-

Name	Type	Description	Required	Default
searchableList	FilterOption[]	Full option list that will be used for searching. Only use it if you need search.	🚫	-

Both hooks return an object that extends the following type

Name	Type	Description
onClear	() => void	Function called when clear button on filter footer is clicked.
onChange	() => void	Function called when apply button on filter footer is clicked.
menu	MenuState	State that handles the popover menu.
status	'error', 'loading', 'ready', 'empty' or 'not-found'	Current status of the filter.
setStatus	(status: FilterStatus) => void	Setter for current status. Only needed on controlled behavior
setFullList	(list: FilterOption[]) => void	Setter for full option list that's used for searching
searchValue	string	Current value in searchbox
deferredSearchValue	string	Debounced search value
matches	FilterOption[]	List of options that match the current search input. This can be set externally or by the filter when there is a fullList and searchValue
setMatches	(newMatches: FilterOption[]) => void	Setter for matches

The return of useFilterState can be used to implement filters with single selection. It contains the same props as the generic type and some more:

Name	Type	Description
combobox	ComboboxState	State used internally that handles rendered options and search
appliedItem	FilterOption	Option that is currently applied.
setAppliedItem	(option: FilterOption) => void	Setter for appliedItem
getFromApplied	(key: string) => T	Shorthand function for fetching any key from the attached object (value) on appliedItem

The return of useFilterMultipleState can be used to implement filters with multiple selection. It contains the same props as the generic type and some more:

Name	Type	Description
combobox	ComboboxMultipleState	State used internally that handles rendered options and search
appliedItems	FilterOption[]	Options that are currently applied.
setAppliedItems	(items: FilterOption[]) => void	Setter for appliedItems
getFromApplied	(key: string) => T[]	Shorthand function for fetching any key from the attached object (value) on appliedItems

Filter group state will control the clear all button, the action should trigger the onClear of each individual filter.

Name	Type	Description	Required	Default
filterStates	FilterState[]	List of filter states for all filters inside the filter group. States can be any of the filter states	✅	-
onClear	() => void	Optional onClear callback, will be triggered when the `Clear all` button is clicked	🚫	-

Name	Type	Description
onClear	() => void	Function triggered when `clear all` is clicked.

The filter control state extends FilterMultipleState and adds some more parameters. The state controls the filter that allows selection of additional hidden filters (FilterControl component) and the visibility of FilterOptional

Name	Type	Description
addFilter	(filter: FilterOption) => void	Function for adding one of the optional filters into the visible filters list.
removeFilter	(filter: FilterOption) => void	Function for removing one of the optional filters into the visible filters list.
items	FilterOption[]	List of all optional filters (visible or not).
visible	FilterOption[]	List of all optional currently visible filters.
setVisible	(list: FilterOption[]) => void	Setter for visible filters list.
shouldOpenOnMount	(filterId: string) => boolean	Function that calculates if some filter (with id `filterId`) should be mounted with its menu open.

Anatomy

There are four types of filters that can be composed with admin-ui's filter components. They are implemented by nesting the composable filter components to form specific structures.

FilterGroup
|__ FilterDisclosure
|__ FilterPopover
    |__ FilterListbox
    |   |__ FilterOptionRadio
    |   |__ FilterOptionRadio
    |   |__ . . .
    |__ FilterFooter

FilterGroup
|__ FilterDisclosure
|__ FilterPopover
    |__ FilterListbox
    |   |__ FilterOptionCheckbox
    |   |__ FilterOptionCheckbox
    |   |__ . . .
    |__ FilterFooter

The searchable filter is just an extension of the simple filter, with the addition of a searchbox.

FilterGroup
|__ FilterDisclosure
|__ FilterPopover
    |__ FilterSearchbox
    |__ FilterListbox
    |   |__ FilterOptionRadio
    |   |__ FilterOptionRadio
    |   |__ . . .
    |__ FilterFooter

Multiselect searchable filter is just an extension of the multiple selection filter.

FilterGroup
|__ FilterDisclosure
|__ FilterPopover
    |__ FilterSearchbox
    |__ FilterListbox
    |   |__ FilterOptionCheckbox
    |   |__ FilterOptionCheckbox
    |   |__ . . .
    |__ FilterFooter

Optional filters are initially hidden on the group bar and are enabled through the filter control filter. A filter is considered optional when it's wrapped with FilterOptional

FilterGroup
|__ . . . (normal filter)
|__ . . .
|__ . . .
|__ FilterOptional
|    |__ FilterDisclosure
|    |__ FilterPopover
|    |  |__ FilterListbox
|    |  |__ FilterOption
|    |  |__ . . .
|    |__ FilterFooter
|_ FilterControl

When to use a Tab, Search, or Button instead of a Filter?

Choose the Tab component to draw attention to a particular Filter that is relevant for every merchant and has up to five options, when there is no need to have a single view containing all information.
Choose the Search component to filter by free-form content that can't be classified into predefined options.
Choose the Button component to lead to a separate list when certain items should not be displayed together. For example, to view archived items separate from active items.

When to use a Checkbox or a Radio for Filter options?

Use a Checkbox when merchants can choose multiple Filter options.
Use a Radio when merchants can choose a single Filter option.

When to include the Footer in a Filter?

Always, for both Radio and Checkbox Filter options, to ensure consistent behavior.

When to include Search in a Filter?

When there are more than five Filter options.

When to include a control to show or hide additional Filters?

When there are more than five Filters available, allow merchants to show the remaining filters on demand.

Where should Filters be positioned in a container?

Considering left-to-right interfaces, follow these recommendations:

Position Filters directly above the content that will be filtered.
Use the DataView component for adequate positioning.
When there are multiple Filters in a group, align them to the left.

When should the list state be stored in the URL or in a saved view?

The complete search query, which includes the Filters, the current page, and the search terms, should be reflected in the URL. This allows the merchant to return to the customized view and share it easily.
If merchants recurrently use a filtered view, consider implementing the option to save views while retaining the search query in the URL.

What to avoid:

Don't use local storage or cookies to store the query.

When to truncate multiple selected Filter options or Filter options with long labels?

By default, the component shows the first option and the count of other selected options. When the Filters in a group don't fit in a single line, they should break a line.

When to use a loading Filter?

When options take more than one second to load for the first time or during a search.

What to avoid:

Don't show the loading state after a Filter is selected or applied. The popover should be immediately closed after a filter is applied and the DataView loading state should be displayed if necessary.

When should the Filter have a preselected value?

Filters shouldn't have a preselected value.

What to avoid:

Don't pre-filter items due to system limitations. API requests should be paginated to avoid overload.

What should be the label of Filters?

Include the name of the property that is being listed. For example, use the label Status when the options are Active, Inactive and Archived.
If the name of the property is already shown in a column label of a Table, for example, reuse the same name.
Use sentence case, but capitalize proper nouns.

What to avoid:

Don't include redundant words. For example, don't use Product status as the label for a Filter in a page that includes Products in its title – use only Status.
Don't use verbs. For example, instead of Select status, use only Status.
Don't use interrogations.

What should be the order of Filters in a group?

Order Filters from most to least frequently used.

What should be the label of Filter options?

When the Filter options are categorized property values, such as a date Filter with dates categorized into ranges, follow these recommendations:

Use sentence case, but capitalize proper nouns.

What to avoid:

Don't write long Filter option labels.
Don't include redundant words. For example, use only Permanent and Temporary instead of Permanent error and Temporary error.
Don't include negative words. For example, write More than 6 months instead of Not in the last 6 months.
Don't use personal pronouns. For example, write Current account instead of My account

What should be the order of options in a Filter?

Order options using the following criteria:

Option with most items to option with least items.
Most recent to least recent.
Most to least frequently used.
Alphabetical order.

What is this?
Composition
Filter
Filter with multiple selection
Filter with search
Filter with multiple selection and search
Examples

What is this?​

Composition​

Filter​

Filter with multiple selection​

Filter with search​

Filter with multiple selection and search​

Filter group​

Group with additional hidden filters​

Error status​

Other status​

Examples​

Internationalization​

Filter with async data fetching​

Filter with async searching​

Usage​

State​

Filter option type​

useFilterState and useFilterMultipleState props​

Shared generic filter state​

Filter state​

Filter multiple state​

useFilterGroupState props​

Filter group state​

Filter control state​

Anatomy​

Basic filter composable component anatomy​

Multiple selection filter composable component anatomy​

Searchable filter composable component anatomy​

Searchable filter with multiple option selection anatomy​

Filter group with optional filters​

Components​

When to use a Tab, Search, or Button instead of a Filter?

Variants​

When to use a Checkbox or a Radio for Filter options?

When to include the Footer in a Filter?

When to include Search in a Filter?

When to include a control to show or hide additional Filters?

Position​

Where should Filters be positioned in a container?

Behavior​

When should the list state be stored in the URL or in a saved view?

When to truncate multiple selected Filter options or Filter options with long labels?

When to use a loading Filter?

When should the Filter have a preselected value?

Content​

What should be the label of Filters?

What should be the order of Filters in a group?

What should be the label of Filter options?

What should be the order of options in a Filter?

What is this?

Composition

Filter

Filter with multiple selection

Filter with search

Filter with multiple selection and search

Filter group

Group with additional hidden filters

Error status

Other status

Examples

Internationalization

Filter with async data fetching

Filter with async searching

Usage

State

Filter option type

useFilterState and useFilterMultipleState props

Shared generic filter state

Filter state

Filter multiple state

useFilterGroupState props

Filter group state

Filter control state

Anatomy

Basic filter composable component anatomy

Multiple selection filter composable component anatomy

Searchable filter composable component anatomy

Searchable filter with multiple option selection anatomy

Filter group with optional filters

Components

Variants

Position

Behavior

Content