Updated: December 19, 2016

SAPUI5 Version 1.36

Filter Bar / Smart Filter Bar

sap.ui.comp.filterbar.FilterBar & sap.ui.comp.filterbar.SmartFilterBar

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

Information

From a UX point of view, the filter bar and the smart filter bar work in the same way even though they are generated differently. The filter bar is configured by app developers, while the smart filter bar is generated from data services and provides a variety of automatic functions. This article contains information about both filter bars.

Responsiveness

Because tables appear in many apps, from simple to complex ones, the filter bar needs to be able 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. The desktop mode (XL/L) and tablet mode (M) provide a special optimization (expanded filter bar) to make use of the desktop’s additional screen real estate.

Size S (Smartphones)

Filter bar (size S)

Filter dialog (size S)

Size M (Tablet)

Filter bar

Filter dialog (size M)

Size L/XL (Desktops)

Collapsed filter bar (size L/XL)

Filter dialog (size L/XL)

Expanded filter bar (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. 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.

Filters dialog

Expanded Filter Bar (Desktop and Tablet Only)

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.

Expanded filter bar (desktop only)

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. On the right side, the user can expand or collapse the filter bar (Show Filter Bar), open the filter dialog to view all filters for the selected variant (Filters (x), where “x” stands for the number of active filters), and execute the current filter set by clicking the Go button. The collapsed filter bar is available across all devices. If required by the use case, the filter bar can be expanded by default.

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 expand mechanism is only available on desktop devices.

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 then. Filters are arranged into their respective filter groups. The user can search for a specific filter by name by using the search bar at the top. Inside the filter dialog, a variant selector is available to quickly switch between variants (you can hide the variant selector if it does not fit the app’s use case). The variant name also indicates if a variant has been modified. 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.
Note: Due to technical challenges, a Close button appears instead of the Cancel button. As an interim solution, the Close button only closes the dialog, but does not undo any changes.
Clear: Clears all input fields/filters (you can hide this button if it does not fit the app’s use case).
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.

On desktops, the user can add filters to the expanded filter bar by selecting the relevant checkbox next to the filter (for example, frequently-edited or important filters).

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.

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.

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. Furthermore, the variant indicates its modified state with the variant selector. Note: Adding a filter to the variant (as shown) does not automatically add the new filter to the personalized expanded filter bar.

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

Note: The expanded filter bar is only available on desktops.

Guidelines

Default Variant Filters

Only important and frequently used filters should be selected for the app-defined initial filter subset hosted inside the expanded filter bar. Which filter should be added to the expanded filter bar generally depends on the use case and the user’s personal preference.

Default variant

Table Filtering and Table Searching

Because the filters of the filter bar and the filter option of the table can contain confusing or even contradictory entries, you must deactivate the filter option of the table.

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 is located next to the variant management. If the filter bar is collapsed, the basic search field is the only input that is still visible. The basic search field is the only one that cannot be excluded from the filter bar via the filter dialog.

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

Basic search field – Filter bar expanded

Basic search field – Filter bar collapsed

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 essential in manual update mode. If a search field is used, it is only triggered by the Go button, and not instantly.

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)