Filter group

// 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';

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.

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.

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.

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.

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.

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

• Figma
• Default CodeSandbox example
• Empty state CodeSandbox example
• Custom date range CodeSandbox example

• https://github.com/twilio-labs/paste/discussions/2017
• https://github.com/twilio-labs/paste/discussions/1979
• https://github.com/twilio-labs/paste/discussions/1702