Intro

The contextual filter allows you to show a prefiltered view of a list, such as a master list.

warning

Note that this filter prevents the regular filter (which is triggered from the filter bar or table toolbar) from displaying the filter criteria that are currently selected.

Usage

Use the contextual filter if:

You want to show the user a meaningful extract of an otherwise highly complex list.
Your app handles very large object lists, and you need to improve performance.

Do not use the contextual filter if:

You just want to provide a way to filter a list. In this case, use the regular filter instead.

Responsiveness

The contextual filter (sap.m.toolbar) spans the whole width of the list or table it is attached to, while its height remains unchanged. Text inside the bar does not wrap if there is insufficient space, but becomes truncated.

Contextual filter – Responsiveness

Contextual filter – Responsiveness

Contextual filter with truncated text in a narrow container, such as on a smartphone.
Responsive behavior on wider screens, such as on a tablet or desktop.

Layout

The contextual filter is shown as a bar directly above the master list. It comprises two parts:

The filter value on the left (for example, a customer name).
The icon for the filter criterion on the right (here, the object type “customer”). The icon helps the user to put the filter value into context.

Contextual filter – Layout

Contextual filter – Layout

Behavior and Interaction

The following example shows a prefiltered master list and explains how to change the filter criterion.

Change Filter

The user opens the app and sees a prefiltered list of objects. The bar on top of the master list indicates that the list is filtered, and which filters have been applied.

When the user clicks the bar, a screen (on phones) or popup (on desktops/tablets) appears for selecting additional filter criteria.

Contextual filter – Change filter setting

Contextual filter – Change filter setting

Select Filter Criterion

In this use case, the user should not be able to disable the filter because there is no way to reset it.

Other master list functions (such as Search or Refresh) are still available and remain unaffected by the contextual filter.

Once a criterion has been selected, the user is taken back to the master list (on phones) or the popup closes (on desktops/tablets). The list is now filtered by the newly selected criterion.

Contextual filter – Select filter attribute

Contextual filter – Select filter attribute

Guidelines

Do not use the contextual filter in place of the regular filter in the footer bar. The regular filter is much more versatile and can also be deactivated by the user.

Also note that both the contextual filter and the regular filter use the same infobar to visualize the filter criteria. If the contextual filter is being used, the regular filter can no longer be visualized. Although both filters can technically be used in parallel, we strongly advise against having both in one list.

Use an icon that is unique and visually represents the current filter criterion.

Do not use any of the generic filter icons. They may be confused with the user-triggered filters.

Don't

Properties

The contextual filter is not a separate control. To build a contextual filter, you need to use the sap.m.OverflowToolbar control. The filtering itself must be implemented by the app team.

Exceptions

There is one special case where the contextual filter can actually be cancelled by the user. This applies when the contextual filter is used to prefilter the items listed in a select dialog.

This use of the contextual filter conveniently offers users a narrowed-down list based on their previous selection.

(1) Initial situation: The user is about to select an account and a contact.

(2) The user selects “Best Electronics” and then clicks the value help icon in the Contact field.

(3) The value help dialog appears showing a list of contacts. These are prefiltered (using the contextual filter) to show only contacts from “Best Electronics” (the company the user selected previously).

Note that this time the icon in the filter’s toolbar does not show an account icon, but a Remove icon :icon-sys-cancel instead. This allows the user to cancel the filter if he or she wants to add a contact that is not associated with the account selected previously.

When the user clicks the Remove icon :icon-sys-cancel, the filter is removed and the entire contact list is shown.

Once the user has selected a contact, the dialog closes and the name is added to the relevant field on the main page.

Opening the value help again resets the dialog to its initial state with the filter set to “Best Electronics”.