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:

• ResolverRenderProps<T, JSX.Element>

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:

• ResolverRenderProps<T, null>

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

Name	Type	Description	Required	Default
conjunction	Conjunction	FilterBar initial conjunction	✅	-
onApply	(filters: Filters<T>) => void	Render props function that is called when the user hits the apply button	✅	-
statements	Statement<T>[]	FilterBar initial statements	🚫	[]
filters	Filter<T>[]	FilterBar filters	🚫	[]

Props

Name	Type	Description	Required	Default
label	string	FilterBar label. It appears when there are no statements	✅	-
internalLabels	InternalLabels	Set of FilterBar internal labels	✅	-
state	UseFilterBarStateReturn<V,T>	Object that manages the component state logic	✅	-
conjunctions	Conjunction[]	FilterBar conjunction options	✅	-
csx	StyleObject	Custom styles	🚫	{}
resolvers	Record<String, Resolver<V, T>>	FilterBar resolvers	🚫	baseResolvers<T>()