When to use filtering patterns

Search and filter components in GitLab may seem similar at a first glance since the UI is similar, but their purposes are generally quite different. Search lets a user find records based on a particular value, while filters let a user display a list of records that meet a common value. The main factor for choosing between these two components should be the user’s goal:

  • If the user is looking for a specific item, the search component should be used. For example, trying to find a particular group member by name, surname, or username.
  • If the user is looking to narrow down a list of items based on specific parameters (single or multiple values), the filter component should be used. For example, narrowing down a list of issues for a particular team member and milestone.

However, raw text strings can still be entered into the filter component, which gives it the ability to search for specific items on top of its filtering capabilities. Consult the table below when deciding which component to use.

User intentComponent
Searching for something specific when the search term or value is knownSearch
Searching for something specific when only some parameters are knownFilter
Narrowing down a range of items based on parametersFilter
Narrowing down a range of items based on parameters, while also searching for something specificFilter

Data complexity and filtering patterns

The filter component, alongside tabs, sorting, date picker, and search can all be used when filtering data. The more complex the data that needs to be filtered, the more components can be used to filter it and change the view. For example, a list of members where their name, username, and join date are the data, the sorting and search components are enough to allow users to efficiently search and order the results. If the data also includes the status for each member (active or inactive), adding tabs to allow users to navigate between all, active, and inactive members would add another useful level of filtering. Consult the table below for general guidance and examples on when to use components for filtering based on data complexity.

Data complexity from 1 (low) to 5 (high)Data examplesComponents
1Member name, usernameSearch
1Member name, username, join dateSearch, Sorting
3Member name, username, join date, statusSearch, sorting, tabs
4List of project or group namesFilter
5Lists of issues or merge requestsFilter, sorting, tabs
Add pattern and component placement guidelines. Create an issue

Last updated at: