Skip to main content
Version: 13.x (Current)

Filter Drawer



The Filter Drawer allows to compile a filter and signal the need for it to be applied on top of the already applied filters. In particular, submitting the Filter Drawer injects the compiled filter into the payload of an add-filter event, which is listened by components such as the Filters Manger.

The Filter Drawer becomes visible whenever the request to provide support for applying filters is signaled. That is, whenever events filter or change-filter are received. The change-filter event allows to carry an object representation of a filter in its payload that is used by the Filter Drawer to initialize its fields.

How to configure

For its most basic usage, the Filter Drawer requires a data-schema describing the fields of the collection to filter.

"tag": "bk-filter-drawer",
"properties": {
"dataSchema": {
"type": "object",
"properties": {
"_id": {"type": "string"},
"name": {"type": "string"}

Filters Options

Data-schema supports options that are specific for how the data should be interpreted within the context of data filtering.

In particular,

  • hidden controls whether the property should not be available to be selected for compiling a filter
  • availableOperators controls what operators should be available for the given property. Note that the type of each property also limits the available operators

Lookup fields (writable views)

The Filter Drawer renders the filter value field as a select or a multi-select for fields described inside the data-schema as having type object or array and format lookup.

Options for such fields will be dynamically fetched from the endpoint specified in basePath property, using the /lookup route provided by the CRUD Service to writable views (version 6.9.0 or higher) , which returns a list of objects. Each option fetched like this should have at least a label field, which is used as display value inside the form, and a value field which is used as unique identifier for such option.


The texts of the Filter Drawer can be customized through the property customLocale, which accepts an object shaped like the following:

type Locale = {
title: LocalizedText
description: LocalizedText
ctaLabel: LocalizedText
propertyPlaceholder: LocalizedText
operatorPlaceholder: LocalizedText
valueInputPlaceholder: LocalizedText
valueSelectPlaceholder: LocalizedText
namePlaceholder: LocalizedText
propertyRequired: LocalizedText
operatorRequired: LocalizedText
valueRequired: LocalizedText
valueLabelMap: {
between: {
start: LocalizedText
stop: LocalizedText
notBetween: {
start: LocalizedText
stop: LocalizedText
validationMessages: {
array: LocalizedText
file: LocalizedText
object: LocalizedText
operators: {
equals: LocalizedText
exists: LocalizedText
doesNotEqual: LocalizedText
contains: LocalizedText
startsWith: LocalizedText
endsWith: LocalizedText
before: LocalizedText
beforeOrEqual: LocalizedText
on: LocalizedText
notOn: LocalizedText
after: LocalizedText
afterOrEqual: LocalizedText
is: LocalizedText
isNot: LocalizedText
greater: LocalizedText
greaterOrEqual: LocalizedText
less: LocalizedText
lessOrEqual: LocalizedText
includesSome: LocalizedText
includesAll: LocalizedText
includesExactly: LocalizedText
doesNotInclude: LocalizedText
between: LocalizedText
notBetween: LocalizedText
hasLengthEqual: LocalizedText
hasLengthGreaterEqual: LocalizedText
hasLengthLessEqual: LocalizedText
datePicker: {
lang: {
locale: LocalizedText
placeholder: LocalizedText
rangePlaceholder: {
start: LocalizedText
stop: LocalizedText
today: LocalizedText
now: LocalizedText
backToToday: LocalizedText
ok: LocalizedText
clear: LocalizedText
month: LocalizedText
year: LocalizedText
timeSelect: LocalizedText
dateSelect: LocalizedText
monthSelect: LocalizedText
yearSelect: LocalizedText
decadeSelect: LocalizedText
monthBeforeYear: 'true' | 'false'
previousMonth: LocalizedText
nextMonth: LocalizedText
previousYear: LocalizedText
nextYear: LocalizedText
previousDecade: LocalizedText
nextDecade: LocalizedText
previousCentury: LocalizedText
nextCentury: LocalizedText
placeholder: LocalizedText
true: LocalizedText
false: LocalizedText


Example: Basic Usage

Through a Filter Drawer configured like:

"tag": "bk-filter-drawer",
"properties": {
"dataSchema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"price": {"type": "number"}

it is possible to create a filter on property "name" and a filter on property "price". After selecting the desired property, the Filter Drawer allows to select an operator for the filter among those that are compatible with the property type. Finally, a value can be provided. The kind input field to provide the value changes according to the type and format of the selected property, as well as the operator. Upon submission, the resulting filter is propagated through the payload of an add-filter event. For instance,

"label": "add-filter",
"payload": {
"property": "name",
"operator": "contains",
"value": "Smith"

Example: Filters options

With a Filter Drawer configured like:

"tag": "bk-filter-drawer",
"properties": {
"dataSchema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"filtersOptions": {
"hidden": true
"price": {
"type": "number",
"filtersOptions": {
"availableOperators": ["equals", "doesNotEqual"]

Due to the value of filtersOptions fields in the data-schema, it is possible to compile a filter only for property "price", and only based on operators "equal" and "doesNotEqual".


Properties & Attributes

dataSchema-ExtendedJSONSchema7Definition-data-schema describing the fields of the collection to query
liveSearchItemsLimitlive-search-items-limitnumber10max items to fetch on regex live search
liveSearchTimeoutlive-search-timeoutnumber5000live-search timeout
rootElementSelectorroot-element-selectorstring-root element to append the drawer to
widthwidthstring-width occupied by the component
editorHeighteditor-heightstring | number-height of object/array editor
basePath-string-endpoint to use to fetch lookup options

Listens to

filterclaims the drawer, closing concurrent ones, to enter a new filter
change-filterenters filter edit mode
lookup-datareceives lookup data
loading-datasets the component to loading state


add-filterwhen done filling the form, notices deployment of a new filter