Skip to contentSkip to navigationSkip to topbar
Figma
Star

Filter group

The filter group pattern allows the user to filter lists, tables, and any other collection of data.


Ingredients

Ingredients page anchor

Select

// import all components for filter group patterns

import {Select} from '@twilio-paste/core/select';
import {Combobox} from '@twilio-paste/core/combobox';
import {Input} from '@twilio-paste/core/input';
import {Separator} from '@twilio-paste/core/separator';
import {Button} from '@twilio-paste/core/button';

General

General page anchor

The filter group pattern should be used when a user is presented with a page containing a large amount of data that they could be filtering or searching through.

Which filter parameters and functionality you can surface to the user will be highly dependent on the page use case. This pattern should serve as a guide to start with as you design and build your filter group, but will likely be very unique to your specific product or use case.

Be judicious in which filters you make available for your users to represent the most common methods they would be using to reduce the entire data set. Filters being included in the filter group should almost always represent data being displayed in the page data set.


Room SIDUnique NameRoom TypeParticipantsDate Completed
RM76426b3e9986878d6316a22bf02d6fc3Test RoomGroup50
RMmg889qwslt6bijmzfjxleq4fn3eyxwdj6Quick SyncPeer to Peer3
RM8fcu56sr0tz6cf9a2phf5zo8vv5m65697My 1:1WebRTC Go2
RM1z17xfzcjdgwf254jk3k0gtu3r7xzxo0lTeam MeetingGroup23
RMx2fw108pgls48zzf4oh6uzl4ly4s4j6b8All HandsGroup41
RMwwxh0rskqqy2wzg7t7f3ha4haavymbnqtProject MeetingGroup6
RMi2or733rf2vd6lziwe8g66smzykqkoplfTest Room 2WebRTC Go1
View example in CodeSandbox(link takes you to an external page)

The filter group pattern relies on the accessibility features built into components included in the group.

When using the filter group, ensure that users:

  • Can easily identify and understand labels for each control
  • Are notified of state changes. For example, when a button changes from the disabled state to the default state
  • Can complete all actions with the keyboard

Simple table filtering should be used when you have a table (or data grid) of data and want to allow users to temporarily filter and/or search for a subset of the dataset for viewing or analysis. This variant should be used when you have a specific amount of parameters you want to allow users to filter by, and not allow users to add their own custom query logic.

The following states/logic should be used in your filter group:

  • The default value for all filters should be the “All” option, and when the “Clear all” link style button is clicked it should revert all filter parameters back to this default state. The only filter that should have a different default would be the date / time select, which would instead show the default time range your team designated.
  • The filters would all be applied as a single call when the “Apply” button is clicked, instead of filtering the table each time a single filter parameter value is selected.
  • It is recommended to use the Skeleton Loader when loading the results of the filters and/or search.
  • The “Apply” and “Clear all” buttons should be in the disabled state on page load, and would enable when at least one of the filter parameters value is changed from the previous state.
  • When using the search input field, users can submit a search by hitting the “enter” key. If the search input is for live filtering, results should update immediately upon load without hitting enter, while being mindful of performance.

Always consider opportunities to reduce cognitive load by limiting the number of filters presented. For the simple table filter group we recommend including no more than 5 filters. If you need to include more than 5 filters, please refer to the complex table filtering variation.

Default state

Default state page anchor

Room SIDUnique NameRoom TypeParticipantsDate Completed
RM76426b3e9986878d6316a22bf02d6fc3Test RoomGroup50
RMmg889qwslt6bijmzfjxleq4fn3eyxwdj6Quick SyncPeer to Peer3
RM8fcu56sr0tz6cf9a2phf5zo8vv5m65697My 1:1WebRTC Go2
RM1z17xfzcjdgwf254jk3k0gtu3r7xzxo0lTeam MeetingGroup23
RMx2fw108pgls48zzf4oh6uzl4ly4s4j6b8All HandsGroup41
RMwwxh0rskqqy2wzg7t7f3ha4haavymbnqtProject MeetingGroup6
RMi2or733rf2vd6lziwe8g66smzykqkoplfTest Room 2WebRTC Go1
View example in CodeSandbox(link takes you to an external page)

When the applied filters and/or search does not return any results, use the Empty State pattern to inform the user and provide a method to reset all filter and search criteria.


Room SIDUnique NameRoom TypeParticipantsDate Completed
RM76426b3e9986878d6316a22bf02d6fc3Test RoomGroup50
RMmg889qwslt6bijmzfjxleq4fn3eyxwdj6Quick SyncPeer to Peer3
RM8fcu56sr0tz6cf9a2phf5zo8vv5m65697My 1:1WebRTC Go2
RM1z17xfzcjdgwf254jk3k0gtu3r7xzxo0lTeam MeetingGroup23
RMx2fw108pgls48zzf4oh6uzl4ly4s4j6b8All HandsGroup41
RMwwxh0rskqqy2wzg7t7f3ha4haavymbnqtProject MeetingGroup6
RMi2or733rf2vd6lziwe8g66smzykqkoplfTest Room 2WebRTC Go1
View example in CodeSandbox(link takes you to an external page)

While we don’t yet have an official custom date/time component, in the interim it is recommended to use the following combination of Popover, Date Input, and Time Input to allow customers to select a custom date/time range.

When the Custom option is selected, the Popover containing the Date Inputs and Time Inputs necessary would be displayed to allow customers to enter their desired range. Once the Apply button is clicked, the Popover would hide. If a customer wants to change their original selections, they must click on the Calendar link style button to open the Popover again.


Room SIDUnique NameRoom TypeParticipantsDate Completed
RM76426b3e9986878d6316a22bf02d6fc3Test RoomGroup50
RMmg889qwslt6bijmzfjxleq4fn3eyxwdj6Quick SyncPeer to Peer3
RM8fcu56sr0tz6cf9a2phf5zo8vv5m65697My 1:1WebRTC Go2
RM1z17xfzcjdgwf254jk3k0gtu3r7xzxo0lTeam MeetingGroup23
RMx2fw108pgls48zzf4oh6uzl4ly4s4j6b8All HandsGroup41
RMwwxh0rskqqy2wzg7t7f3ha4haavymbnqtProject MeetingGroup6
RMi2or733rf2vd6lziwe8g66smzykqkoplfTest Room 2WebRTC Go1
View example in CodeSandbox(link takes you to an external page)
Do

Include up to 5 filters in the simple table filter group.

Don't

Don’t Include more than 5 filters in the simple table filter group.

Do

The search input should utilize the placeholder copy to make it very obvious to users what they should enter into the field to search.

Don't

Don’t use vague placeholder copy in the search field.

Do

The search input should be labeled directly using aria-label, so it’s accessible. By doing this, it’s not necessary to include a visible label.

Don't

Don’t add a visible label to the search input.

Complex table filtering is for users who are adding more than 5 filter parameters, multi-select filter criteria, selecting custom query rules, and/or creating complex if/else logic without code to filter down a large data table.

(information)

This pattern is coming soon!

We've not created this variant of filter group pattern. If you need this for your current or upcoming work, please consider partnering with us to contribute it.

Insights filtering is for users who are adding deeper query logic for their Insights products.

(information)

This pattern is coming soon!

We've not created this variant of filter group pattern. If you need this for your current or upcoming work, please consider partnering with us to contribute it.