Updated: February 21, 2023

SAPUI5 Version 1.102

Filter Bar

sap.ui.comp.filterbar.FilterBar

Intro

The filter bar filters item lists and tables according to various filter criteria. You can use it for both simple and complex lists, regardless of their size. To handle complex lists with multiple filters, the filter bar provides predefined, customizable filter sets (variants).

The smart filter bar is closely related to the filter bar, as it covers the same use cases. The difference is that the smart filter bar uses annotations to create a filter bar.

Filter bar within the dynamic page

Information

The filter bar now supports the dynamic page. Do not use the filter bar in the sap.m.Page for new SAP Fiori apps. For more information on the differences, see the filter bar guideline for version 1.52.

Responsiveness

Because tables appear in many apps, from simple to complex ones, the filter bar needs to run on all form factors. While the main concept of the filter bar remains stable across the devices, its responsive design adapts the control’s behavior to match the ability of each device.

Size S (Smartphones)

Expanded filter bar - Size S

Collapsed filter bar - Size S

Filter dialog - Size S

Size L (Desktop)

Expanded filter bar - Size L

Collapsed filter bar - Size L

Filter dialog - Size L

Layout

Filter Dialog

The filters inside the filter dialog are arranged in a vertical linear layout. If filter groups are maintained, the filters are visually grouped in sections, with the filter group name at the top. A link at the end of each group allows the user to add or remove filters from that group. The link text is Change Filters if at least one filter is activated, indicating that filters can be added or removed. If no filters have been set for the group, the link text is More Filters, indicating that more filters can be added.

The first group is called “Basic” and contains the preset filters that come with the app. A checkbox next to each filter enables the user to show the corresponding filter on the expanded filter bar. If the checkbox is selected, the filter is shown on the expanded filter bar. If the checkbox is not selected, the filter is only visible within the filter dialog. In both cases, the filter is active if a value is entered.

The vertical layout of the filter dialog remains stable across all devices. To ensure a clean grid layout appearance, the size of the widest input field is inherited by all other filters.

Filter dialog (size L)

Expanded Filter Bar

The expanded filter bar arranges the input fields in a simple horizontal linear layout. If the browser’s window size is reduced or the filters exceed the first line, a simple mechanism opens a new line of filters. The height of the expanded filter bar is not limited and adjusts to accommodate the filters that need to be shown. The label is always above the input field. As in the filter dialog, the size of the widest input field is inherited by all other filters. This avoids having unstable and busy-looking grid layouts.

Filter bar (size L) with one row of filters

Filter bar (size L) with more than one row of filters

Filter bar (size S) with vertical filters

Components

Collapsed Filter Bar

The collapsed filter bar takes up very little space, leaving the bulk of the screen to display the actual results. However, the variant selector in the upper left corner is still available for switching between variants. The user can expand or collapse the filter bar by clicking the header. If required by the use case, the filter bar can be expanded by default.

On desktop and tablet devices, the collapsed filter bar shows a summary of the filters currently applied. It shows Filtered By (x):, where “x” stands for the number of applied filters. This is followed by a comma-separated list of the filters currently applied. Up to 5 filters are listed. If more filters have been applied, an ellipsis (…) shows at the end of the string. If no filters have been applied, the summary text is Not Filtered.

Collapsed filter bar

Expanded Filter Bar

Developer Hint

Smart filter bar: See the parameters for configuring the expanded filter bar.

In addition to the collapsed filter bar, the expanded filter bar shows a user-defined filter subset of the currently selected variant.

The Adapt Filters (x) link opens the filter dialog, and allows the user to add filters or hide them. The Go button triggers the filter. The Go button is only shown in manual mode.

Expanded filter bar

Filter Dialog

Developer Hint

Smart filter bar: See the parameters for configuring the filter dialog.

The filter dialog is the central component that shows all filters of the selected variant, allowing the user to add filters to the variant or remove them. Filters are arranged into their respective filter groups. The user can search for a specific filter by name in the search bar at the top.

The footer toolbar at the bottom of the dialog provides the following functions:

Cancel: Closes the dialog and undoes all changes
OK: Executes the selected filter set

The header area of the filter dialog contains a Reset button. This resets the filter to the initial variant values (you can hide this button if it doesn’t fit the app use case). Before the filters are reset, the user gets a warning.

The user can choose to hide filters on the expanded filter bar by deselecting the relevant checkbox next to the filter in the filter dialog (for example, if a filter is rarely edited, or unimportant).

Information

In analytical list page scenarios, the warning for the reset button is not yet available.

Filter dialog

Variant Selector

The variant selector is used to select the current variant, and also provides access to variant management.

Variant selector

Filter/Input Controls

Filter/input controls

When designing the filter bar, pick the simplest input control that works for your use case. Avoid unnecessary complexity in the filter bar.

If there is a predefined list for single or multiple selection, use the select control or combo box control. For temporal information, you can use the date picker or date range selector. To help the user enter a valid value for multi-input fields, you can enable suggestions.

For a comprehensive overview of when to use which input field, see Selection Controls – Overview.

Use the value help control only as a last resort. It is especially beneficial if you want to offer an advanced function for selecting single or multiple items either inline (by entering text) or by means of a dialog.

Developer Hint

For development information, see data types for the smart filter bar.

Recommended input fields:

Behavior and Interaction

The filter bar contains the following actions:

Selecting a Variant

The main use case for the filter bar is to select and execute variants that influence the list of items. In this example, the variant applies its filter set automatically. The item list is filtered without the user needing to click Go.

Selecting a Variant

Personalizing the Expanded Filter Bar

Users can hide a filter on the expanded filter bar by deselecting the checkbox next to the relevant filter in the filter dialog. This allows the user to hide filters that are rarely changed from the extended filter bar, giving complex filters a more lightweight appearance.

Personalizing the Expanded Filter Bar

Saving a New Variant

You can save new filter variants in the variant selector.

Once you have changed an existing variant, an asterisk (*) is displayed next to the current variant name, indicating its “dirty state”.

You can either save the adapted variant with the current name (overwrite), or save it under a new name.

Variant Selector

Open the variant selector and choose Save As. Type your desired variant name into the input field and select OK.

Save new variant in variant selector

Guidelines

Default Variant Filters

For all filter bars, provide a set of predefined default filters that come with the app (“Basic” group in the filter dialog). Include filters that are:

Mandatory / crucial to the use case
Frequently used
Vital for reducing the number of items in the list

Users can hide filters in the “Basic” group, but cannot remove them from the filter dialog.

Default variant "Basic"

Default Values

Provide a meaningful default value for as many filters as possible. Meaningful default values depend on your use case.

A default value for date ranges, for example, should reflect the time frame the user would normally apply. App designers need to decide which time frame is appropriate.

Appropriate default values are particularly crucial for filter sets and list reports that operate on large datasets. In this case, consider making certain default filters mandatory to help the user avoid loading very large datasets unnecessarily.

For list reports and overview pages, ensure that mandatory filter fields always have default values. Otherwise, users will see error messages when the page loads.

Filter without default value

Filter with available values

Filter with a default value

Table Filtering and Table Searching

Provide the user with a central location filtering and searching. If you use a filter bar, do not provide filter options or search options for the control below (for example, a table, chart, or list.). Avoiding multiple filter locations also helps to prevent confusing or contradictory entries (for example between the filter bar and a table filter).

Table without filtering option

Don't

Table with filtering option

Initial State

The filter bar can initially be collapsed or expanded, depending on the use case:

Initial State Collapsed

If the app has a default variant that is executed on loading, the table is prefilled, and the user seldom changes the filters, the app can start with a collapsed filter bar.

Initial State Expanded

If the app does not use a default variant and the user has to set a filter to obtain a first result set for the table, start with an expanded filter bar. Also, if a vast number of items are expected, include some mandatory filters with default values. Since the user first has to enter values for these filters, start with an expanded filter bar. If you are in any doubt, start the app with an expanded filter bar.

Note: At least one filter must be defined to begin with. This filter is set within the basic group by app designers. If the use case allows, and depending on the size of the result set, provide a table that is initially filled.

Initial state collapsed

Initial state expanded

Basic Search Field

The basic search field allows the user to filter the results by a given keyword. In contrast to the other input fields, the basic search field has a placeholder text instead of a label.

Note: If you need to provide a search field, use the basic search field. The search field within the table must be deactivated.

Filter bar with basic search field

Live Update / Manual Update

The filter bar is available in two separate modes: Live update mode and manual update mode.

Live Update

In the live update mode, the filter bar reacts instantly to every input change. The result table is updated every time the user changes a filter field or the search field. Therefore, a Go button is not necessary.

The search is triggered with every letter that is entered, starting with the first letter the user types. The table is updated with the results that match all set filters and include the search term.

Manual Update

In the manual update mode, the filter results are only updated when the user clicks Go. A Go button is therefore mandatory in manual update mode. Pressing ENTER on the keyboard also triggers the filter.

Which Mode Should I Use?

The live update mode is more convenient for the user. However, if the user has to configure multiple filters to obtain a useful result set, or if the resulting traffic is expected to be excessively high, consider using the manual update mode instead.

Filter bar in live update mode

Filter bar in manual update mode

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Smart Filter Bar (guidelines)
Variant Management (guidelines)

Implementation

Filter Bar (SAPUI5 samples)
Filter Bar (SAPUI5 API reference)
Smart Filter Bar (SAPUI5 samples)
Smart Filter Bar (SAPUI5 API reference)
Filter Item (SAPUI5 API reference)
Filter Group Item (SAPUI5 API reference)