Filter

Filters are supposed to be used in pages or sections that display some kind of data that can be filtered. The filter component is a picker that displays filter options and allows for only one of them to be selected. When one of the options is selected it should produce a change on the data or content being displayed, and should be filtered accordingly.

Usage

import {
  experimental_Filter as Filter,
  experimental_useFilterState as useFilterState,
} from '@vtex/admin-ui'

function Example() {
  const state = useFilterState({
    items: [
      { label: 'Available', value: 1, id: '#1' },
      { label: 'Sold out', value: 2, id: '#2' },
    ],
    onChange: () => {},
    label: 'Status',
  })
  return <Filter state={state} />
}

Examples

Initial values

const Filter = experimental_Filter
const useFilterState = experimental_useFilterState

function Example() {
  const state = useFilterState({
    items: [
      { label: 'Available', value: 1, id: '#1' },
      { label: 'Sold out', value: 2, id: '#2' },
    ],
    onChange: ({ selected }) => console.log(`applied: ${selected.label}`),
    label: 'Status',
    initialApplied: { label: 'Available', value: 1, id: '#1' },
  })
  return <Filter state={state} />
}

useEffect(() => {
    state.setAppliedItem({ label: 'Available', value: 1, id: '#1' })
  }, [])

render(<Example />)

Custom shaped object

const Filter = experimental_Filter
const useFilterState = experimental_useFilterState

function Example() {
  const state = useFilterState({
    items: [
      { name: 'Available', value: 1, uniqueId: '#1' },
      { name: 'Sold out', value: 2, uniqueId: '#2' },
    ],
    onChange: ({ selected }) => console.log(`applied: ${selected.name}`),
    label: 'Status',
    getOptionId: (option) => option.uniqueId,
    getOptionLabel: (option) => option.name,
  })
  return <Filter state={state} />
}

render(<Example />)

I18n

The filter has default translations. Wrap your app with I18nProvider to configure the locale.

import {
  experimental_Filter as Filter,
  experimental_useFilterState as useFilterState,
} from '@vtex/admin-ui'

function Filter() {
  const state = useFilterState({
    items: [
      { label: 'Available', value: 1, id: '#1' },
      { label: 'Sold out', value: 2, id: '#2' },
    ],
    onChange: ({selected}) => console.log(selected.label),
    label: 'Status',
  })
  return <Filter state={state} />
}

function RootApp() {
  return (
    <I18nProvider locale="ko-KO">
      <Filter />
    </I18nProvider>
  )
}

render(<RootApp />)

Props

Filter

Name	Type	Description	Required	Default
state	FilterState	Object that manages the component state logic, you can obtain it calling the useFilterState hook	✅	-

useFilterState

Name	Type	Description	Required	Default
items	T[]	List of options for the filter, if you don't set getters for label and id then the fields label and id by default	✅	-
label	string	Filter button label	✅	-
onChange	({selected: T}) => void	Callback called with current selected item on apply or clear press.	🚫	-
baseId	string	Optional baseId for controling the components and its childrens id	🚫	-
getOptionId	(item: T) => string	Optional function to get the id from custom objects	🚫	(option) => option.id
getOptionLabel	(item: T) => string	Optional function to get the id from custom objects	🚫	(option) => option.label

FilterState (return of useFilterState)

Name	Type	Description
menu	MenuState	State that controls the component's popover menu
combobox	ComboboxState	State that controls the component's option list
onClear	() => void	Function used by the component when clear is selected
onChange	() => void	Function used by the component when apply is selected
appliedItem	T	Currently applied item
setAppliedItem	(item: T) => void	Function that sets the current applied item
items	T[]	List of options for the filter