Filters
Filters allow users to narrow a set of data based on one or more criteria.
Standard Filter
This variation features an expand/collapse design that displays filters across the top of the screen.
When to Use
- This is the most common variation and should be used in most instances.
When Not to Use
- When there are only 1-2 filter categories, consider the simpler Toolbar variation.
Variations
- Standard Filter (shown above)
- Toolbar Simple Filter
Usage
Types of Filter Criteria
Filter categories may include a variety of form elements, such as:
Display & Behaviors
Accessing Filters
Filters are positioned at the top of the screen, above the corresponding data set. See the Filter Page Template for details on how to position the filter within the context of a screen.
Filters are hidden by default, allowing the focus to be on the initial data set.
In the Standard variation, selecting the “Show Filters” text button expands the set of filters. In the Simple Toolbar variation, selecting the text button or Filter icon within the Toolbar expands a popover with the filter controls.
Once the Standard variation is expanded, up to 4 categories are displayed in the initial view (on larger screen sizes). Prioritize this view based on categories the user is most likely to use. A “Show All” option may appear in the lower left to provide access to less common categories.
A “Show All” link may also appear at the individual category level (for example, when the number of options exceeds 5-6). This may either expand more options immediately below (if there are only a few more) or launch a modal window (if there is a large number of filter values to display).
Data
It is preferred that the data update immediately as the user selects a filter criteria; if this is not technically feasible, an Apply button may appear in the lower right, below the filter set. A progress indicator may also be used in conjunction with the button if the data does not load quickly.
A Clear action may appear for an individual filter category. This allows the user to clear all selections within the corresponding category, including selections made in a modal or expanded view. While a Clear action is not always required, it is necessary to include it for certain input types that the user can’t deselect (radio buttons, for example).
Displaying Applied Filters (Tagging)
In the Standard Filter variation, tags may be displayed to indicate what filters have been applied. This allows the user to see what filters have been applied to the set while still allowing the filter panel to collapse. A clear all link appears next to the tags.
Tag Labels
Most input types will display the value of the filter being applied. (For example, “American Airlines” instead of “Airline: American Airlines”). In some instances, however, it is necessary to display a brief label to make the value clear (For example, filtering by number of passengers would require a label of “1 Passenger” or “Passengers: 1” instead of simply “1”). Always keep clarity in mind when determining what to display in the Applied Filters section.
Responsive Behavior
As the viewable space decreases, the filter categories collapse from four columns to three columns to two columns. At the XS screen size (view component in a new tab and adjust window size), the filter categories collapse into a series of expand/collapse panels.
The following changes also occur at the XS screen size:
- The applied filters tags do not display. Instead, a total count of the filter criteria displays in the upper left.
- A button to apply the filters appears and is locked at the bottom of the viewport.
Toolbar Simple Filter
Toolbar filter allows the ability to access a simple filter (1 or 2 categories) within a Toolbar.
When to Use
- Use when there are only 1 or 2 filter categories and the options within each are minimal.
When Not to Use
- Do not use for more complex filter sets.
Developer Notes
A filter component is constructed using the spark-filter class. The filter header, created using the spark-filter__header class, is used to display the filter toggle buttons as well tags for any applied filters. At the XS screen size, the applied tags are hidden in lieu of a tag indicating how many filters are applied. The spark-filter__content contains the form field filter groupings and buttons that are used to filter data. The filter groups are housed within modules that respond to the screen size to adjust the number of filter groups displayed, with additional groups accessible via a view more button.
The following options may be passed when using new Spark.Filter(el, {}); or $(el).sparkFilter({});:
| Name | Type | Default | Description |
|---|---|---|---|
| onClearAll | function | null | A function to run to when clearing all tags and applied filters. |
| moduleOptions | array | null | An array of options to be applied to specific filter groups/modules in order of appearance. This is detailed further below. |
The following options may be passed in the moduleOptions array:
| Name | Type | Default | Description |
|---|---|---|---|
| onShowAll | string | null | A string denoting the type of action to take on a show all link. The options are `modal` or `toggle`. |
| onModalClose | function | null | A function to run when closing a modal via the Save button. |
| onClear | function | null | A function to run to clear applied filters. |
For all available methods and full API, refer to the component code on Bitbucket.
The Filter template displayed above has been set up with only the first module (Filter Module 1) connected to functions that handle clearing, syncing with the modal, and applying of selected filters. This is because the Filter could have a variety of field configurations within each module, and as such only a single module was selected to be shown as an example.
Instantiating the Filter
The following code is provided as an example on how to instantiate a Filter with different options:
Applying filters and displaying tags
When using the Apply button to submit selected filters, it is required that you add an event listener to the button to allow you to run appropriate functions when a user clicks the button. For instance, this is the point at which tags would be applied, in and the filter collapsed to focus on the result set. The following code is provided as an example to illustrate this concept:
Clearing applied filters within a module
Each module should have a Clear button that allows users to clear any selected filters, particularly in instances where an option cannot be deselected as in the case of radio buttons. By default the Clear button should be in a disabled state until the user changes a predefined value or selects an option from a set that does not have a predefined value. The following code illustrates how a Clear button can be enabled and disabled depending on a users actions:
Clearing an individual tag
When selected filters are applied and the filter container collapsed, the applied filters are displayed using tags, each of which has an X button to clear that specific tag. During the process of applying filters and generating of tags, each tag is supplied a callback function that is run when the user clicks the X button within the tag. The following code illustrates how a tag could be cleared and the associated checkbox unchecked: