Updated: July 23, 2018

SAPUI5 Version 1.56

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).

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 M (Tablet)

Expanded filter bar (size M)

Collapsed filter bar (size M)

Filter dialog (size M)

Size L/XL (Desktops)

Expanded filter bar (size L/XL)

Collapsed filter bar (size L/XL)

Filter dialog (size L/XL)

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)

Filter dialog (size S)

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 on 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 Filtered By: None.

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:

Save: Saves your modified variant filter set (Save and Save As can be provided)
Cancel: Closes the dialog and undoes all changes
Restore: Restores the initial variant values (you can hide this button if it does not fit the app’s use case)
Go: Executes the selected filter set
Clear (optional): Clears all input fields/filters (this button should only be used if it fits the app’s use case)

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).

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

Developer Hint

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

Filter/input controls

Which filter control is used in the filter dialog or the expanded filter bar depends on the use case. Use the value help control 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. If there is a predefined list for single or multiple selection, use the combo box control. For temporal information you can use the date picker or date range selector.

When designing the filter bar, pick the simplest input control that works for your use case. Using more complex controls (like value help) when you don’t actually need them just increases the complexity of the filter bar.

Additionally 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

Adding Filters to a Variant

In the filter dialog the user can access more filters for every filter group. Filters can then be added or removed in a separate dialog. Once a filter has been added or removed, it appears or disappears from the filter dialog. If the user selects the checkbox next to the filter, the filter is displayed on the extended filter bar.

Adding Filters to 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

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.

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. 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

Manual Update / Live Update

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

Manual Update

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

Live Update

With 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 and is not shown if live update mode is used.

Additionally, the search is triggered with every letter that is entered. Starting with the first letter typed in, the table is updated with the results that match all set filters that include the search term.

Which One to Use

Use live update mode by default as it is more convenient for the user. 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 manual update mode instead.

Filter bar in manual update mode

Filter bar in live 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

Variant Management (guidelines)
Smart Filter Bar Annotations (guidelines)

Implementation

Filter Bar (SAPUI5 samples)
Smart Filter Bar (SAPUI5 samples)
Filter Bar (SAPUI5 API reference)
Smart Filter Bar (SAPUI5 API reference)
Variant Management Example (SAPUI5 samples)
Variant Management Example (SAPUI5 API reference)
Filter Item (SAPUI5 API reference)
Filter Group Item (SAPUI5 API reference)