Filter

What is this?

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

Composition

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.

Filter

Loading...

Filter with multiple selection

Loading...

Filter with search

Loading...

Filter with multiple selection and search

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

Loading...

Filter group

Loading...

Group with additional hidden filters

Loading...

Error status

Loading...

Other status

Loading...

Examples

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

Internationalization

Filter supports internationalization of its native messages.

Loading...

Filter with async data fetching

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.

Loading...

Filter with async searching

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.

Loading...

Usage

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 />
  )
}

State

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.

Filter option type

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.	🚫	-

useFilterState and useFilterMultipleState props

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

Shared generic filter state

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

Filter state

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

Filter multiple state

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

useFilterGroupState props

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	🚫	-

Filter group state

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

Filter control state

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.

Basic filter composable component anatomy

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

Multiple selection filter composable component anatomy

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

Searchable filter composable component anatomy

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

Searchable filter with multiple option selection anatomy

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

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

Filter group with optional filters

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

• 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