This library is still in development and is available only for internal usage at VTEX.
Skip to main content

FilterBar

Version: 0.132.0

FilterBar

A component that represents a list of statements that when combined it filters a data.

interface Filters<T> {
/** FilterBar statements */
statements: Statement<T>[]
/** FilterBar conjunction */
conjunction: Conjunction
}

Behavior

Loading...

Import

import { FilterBar } from '@vtex/admin-ui'

Statement

The FilterBar statement is a combination of a filter, a condition, a value, and a conjunction. Important to note that the conjunction value is shared along with all statements.

/**
* @generic T: Type of statement value
* @generic R: Type of resolvers
*/
interface Statement<T, R = BaseResolvers<T>> = {
/** Statement condition */
condition: Condition
/** Statement Filter */
filter: Filter<T, R>
/** Statement value */
target: T
}

Conjunction

Represents the Boolean logic that must be applied between the statements

type Conjunction = {
/** Conjunction label */
label: string
/** Conjunction value */
value: 'and' | 'or'
}

Filter

interface Filter<T, R = BaseResolvers<T>> {
/** Filter label */
label: string
/** Filter id */
id: string
/** Filter conditions */
conditions: Condition[]
/** Filter resolver */
resolver: R
}

Resolvers

You can use this feature to apply predefined filters more easily. For example, you can render a simple select filter without implementing the component from scratch, you just need to pass the requiring properties to our Simple resolver. Check the examples below to go further.

Simple

Use this when you want to render a simple select filter.

Interface
interface SimpleResolver<T> {
/**
* Resolver type
*/
type: 'simple'
/**
* Defines the path to the select item label
* @default 'value'
*/
accessor?: string
/**
* Select items
*/
items: T[]
/**
* Filter default value. When the filter is added it will be the first value applied.
*/
defaultValue: T
/**
* Custom filter render props
*/
render?: (props: ResolverRenderProps<T, JSX.Element>) => ReactNode
}

Check also:

Example
Loading...

Root

Use this when you want to create your specific filter that isn't defined in our resolvers.

Interface
interface RootResolver<T> {
/**
* Resolver type
*/
type: 'root'
/**
* Filter default value. When the filter is added it will be the first value applied.
*/
defaultValue: T
/**
* Custom Filter render props
*/
render: (props: ResolverRenderProps<T, null> => ReactNode
}

Check also:

Example
Loading...

Common Resolver Interfaces

/**
* Resolver render props
* @generic T: Type of statement value
* @generic D: Type of data
*/
interface ResolverRenderProps<T, D = null> {
data: D
/** Respective statement value */
statement: Statement<T>
/** Respective statement index position on FilterBar */
index: number
/** Function that handles the respective statement value change on FilterBar */
handleValueChange: (value: T, index: number) => void
}

Condition

It is represented by the filter conditions.

interface Condition {
/** Condition label */
label: string
/** Condition id */
id: string
}

Value

It is represented by the filter resolver.

Intl

FilterBar component has a lot of internal labels that need to be translated. The way we do this translation, for now, is using properties that add values to these labels.

IMPORTANT NOTE: This is a workaround and it may change in a near future.

Properties

interface InternalLabels {
/**
* Conjunction dropdown aria-label
*/
conjunctionLabel: string
/**
* Filter dropdown aria-label
*/
filterLabel: string
/**
* Condition dropdown aria-label
*/
conditionLabel: string
/**
* Statement menu aria-label
*/
statementMenuLabel: string
/**
* Add filter button label
*/
addFilterLabel: string
/**
* Apply filter button label
*/
applyFilterLabel: string
/**
* Clear filter button label
*/
clearFilterLabel: string
/**
* Duplicate statement button label
*/
duplicateStatementLabel: string
/**
* Delete statement button label
*/
deleteStatementLabel: string
/**
* First statement conjunction label
*/
whereStatementLabel: string
}

useFilterBarState

Hook that manages the state logic of the FilterBar component. It receives two parameters that define the component's initial state: conjunction, and statements.

Parameters

NameTypeDescriptionRequiredDefault
conjunctionConjunctionFilterBar initial conjunction-
onApply(filters: Filters<T>) => voidRender props function that is called when the user hits the apply button-
statementsStatement<T>[]FilterBar initial statements🚫[]
filtersFilter<T>[]FilterBar filters🚫[]

Props

NameTypeDescriptionRequiredDefault
labelstringFilterBar label. It appears when there are no statements-
internalLabelsInternalLabelsSet of FilterBar internal labels-
stateUseFilterBarStateReturn<V,T>Object that manages the component state logic-
conjunctionsConjunction[]FilterBar conjunction options-
csxStyleObjectCustom styles🚫{}
resolversRecord<String, Resolver<V, T>>FilterBar resolvers🚫baseResolvers<T>()