A composite component for filtering data in a table or list.

In the clear mode, filters remain on the panel after clicking the button with a cross, and in the delete mode, they disappear. Do not mix the two modes on one screen. If the buttons with the cross icon work differently for adjacent filters, this will confuse the user.

Use when the system has few filters or users often use several popular parameters. Filter buttons without selected values ​​are pre-showed on the screen, the filled filter is cleared by the cross, but the button itself does not disappear.

In the cleaning mode, you should not give the opportunity to add new filters from the menu, as this will conflict with the fact that the cross will either reset or delete the filter.

In this mode, the user has the option to hide the component if there are no values ​​selected in the filter. When filled, the button with a cross resets the filter values ​​and hides it. Filters with the ability to delete are usually hidden in the menu to avoid cluttering the screen. The user will select the desired parameter from the drop-down list, and then the corresponding element will be added to the filter panel.

A filter can be added to the filter panel regardless of the operating mode, which will always be filled and cannot be cleared. The user will only be able to change its value.

The filter value cannot be changed, the filter can only be deleted.

Clicking on a pseudo-link in the list of parameters will add a new value to the filter. If the filter is not in the menu or in the panel: then an inactive element will be added, the value of which cannot be changed, it can only be deleted.

For the select and multiselect types, the pipe template accepts an optional compareWith — a comparator forwarded to the underlying select that controls how the selected value is matched against the option list. Override it when options are compared by a business key, or when the selected value is a distinct object (e.g. restored from a saved filter) rather than the same reference. When omitted, options are matched by their id. A custom comparator is responsible for its own null handling — unlike the default, which never matches a null/undefined value.

The input type is the only one without a popover: it renders a bare input that is typed into directly in the bar, using the pipe's name as its placeholder. The value is applied as you type — 200 ms after the last keystroke (debounceTime) and only from 3 characters on (minLength) — rather than through an Apply button. Text shorter than the threshold, including an emptied field, is applied as null, so the bar never keeps filtering by text that is no longer in the input. Enter and blur apply the value immediately and ignore the threshold: an explicit action is always applied as typed. Its only clear affordance is the built-in cleaner inside the input, so removable has no effect — an input pipe can only be removed programmatically. Values are trimmed, and a blank value is applied as null. Set its width with the --kbq-filter-bar-pipe-input-width CSS variable.

The date and datetime pipe templates accept optional limits for the custom period. minDateTime and maxDateTime bound the selectable range — the datetime pipe uses the full instant (date and time), the date pipe only the day. minInterval and maxInterval constrain the length of the selected period (end − start) as a duration-like object (e.g. { days: 3 }, { hours: 1 }); a period outside these bounds shows an error and disables Apply, with the limit formatted for the current locale. All four are ignored by other pipe types.

If the filter has many values, it is useful to enable search in the drop-down menu.

If there are many values, "Select All" will allow you to select all values ​​or deselect all values ​​in one action. When searching, the master checkbox selects only the results that match the query.

The multiselect and multi-tree-select pipe templates accept an optional lockedValues — the list of values whose selection cannot be removed. They are always selected: rendered as disabled options with a checked checkbox, kept by clearing the pipe, and folded into an incoming filter value silently, without a change event. A pipe holding nothing but its locked values reads as empty — it renders unfilled and hides its clear button. Note that "reads as empty" is about the UI only: because a pipe's value is meant to be applied as-is, clearing removes just the entries the user was able to select, and both onClearPipe and onChangePipe still carry a value listing the locked ones.

"Select all" ignores them entirely: it neither selects nor deselects a locked option, and the master checkbox reflects only the options the user can actually toggle. Note that under selectedAllEqualsSelectedNothing a full selection is still committed as an empty value — there the locked values are implied rather than listed.

Entries of lockedValues have the same shape as the entries of the owning pipe's value: { name, id } objects for multiselect (matched with compareWith, falling back to id), and raw node values for multi-tree-select. Locking a tree branch locks its whole subtree. The option is ignored by other pipe types.

Because locked options are rendered as disabled, keyboard navigation skips them.

By default the dropdown list of the select, multiselect, tree-select and multi-tree-select pipes is 256px tall — exactly eight 32px options, so a list of eight fits without a scrollbar. Pass panelMaxHeight in the pipe template, in pixels, to change that:

pipeTemplates: KbqPipeTemplate[] = [
    {
        name: 'Select',
        type: KbqPipeTypes.Select,
        values: [/* ... */],
        panelMaxHeight: 160,

        cleanable: false,
        removable: false,
        disabled: false
    }
];

The value caps the scrollable list only, and the list's own padding is added on top of it — so a multiple of the 32px option height fits without a scrollbar and without a clipped row. The pipe's search field is rendered above the list and adds to the panel's total height, while the "select all" row scrolls with the options and is counted by the cap. A value taller than the room left in the viewport is clipped by the overlay rather than scrolled. Omitting the option — or passing null — restores the default. The option is ignored by other pipe types.

The filter value cannot be changed or deleted.

Text search allows you to search for information based on any data, even if there are no separate filters for it.

Search splits a multi-word query into parts and searches for them independently, trims leading and trailing spaces, is case-insensitive, and folds diacritics. The algorithm is described in the Smart search guide.

The user can quickly get search results by selecting a saved filter, without re-configuring the parameters. It is also possible to create a new set of filters and use them in the future.

The filter bar takes its own strings — the filters menu, the reset button, pipe tooltips and the date pipe's custom-period flow — from KbqLocaleService. The data you pass in pipeTemplates and filter is never translated, so in the example below the option names stay in English while the surrounding controls change.

There are three ways to control the locale. KBQ_DEFAULT_LOCALE_ID is the fallback (ru-RU) used when nothing else is provided — it is a plain constant, not an injection token, so it cannot be provided. KBQ_LOCALE_ID fixes the locale once, when KbqLocaleService is constructed; it has to be provided alongside the service itself, because the service reads the token from the injector that created it. KbqLocaleService.setLocale() changes the locale at runtime.

Each bar below provides its own KbqLocaleService, so they are isolated from each other and from the language selector in the footer of this site.