Filter input

Filter input is an input that provides suggestions through qualifiers and highlights complex filter syntax.

This component is currently unavailable and we are seeking contributors to create it.

Overview

An input that provides suggestions through qualifiers and highlights complex filter syntax.

Anatomy

The filter input annotated with specific naming for individual items. The input has a 'label:bug state:open assignee:' value and shows multiple suggestions for users.

Content

Icon

A filter input allows free form text searching as well as using qualifiers to narrow down your search. The filter input always supports free form text search. This is why you should use the search icon as a leading visual. A filter icon could give the impression that free form text search isn't available.

Do
An input that has a magnifying glass icon on the left side.

Use the search icon in a filter input.

Don’t
An input that has a filter icon on the left side which consists of 3 lines getting incrementally smaller.

Don't use a filter icon in a filter input.

Submit

There are two ways this component can trigger submission of the input value.

  1. Auto update results as the value changes (recommended)
  2. Provide a search button next to the filter input
Do
A focused filter input with value 'label:bug state:open abc' indicating that when it should instantly filter results on the page and debounce this if using API calls.

Auto update results based on when the input value changes.

Don’t
A focused filter input with value 'label:bug state:open abc' suggesting a `Submit/Start search` item.

Don't add an item to submit the current value.

Clear button

The clear button only appears when there is at least one character entered in the input. When the input is empty the clear button disappears again.

Do
An input without a value.

Hide the clear button when the input is empty.

Don’t
An input without a value showing a clear button on the right.

Don't show the clear button when the input is empty.

Use an icon instead of a link for clearing the input. This avoids confusion with the value of the input. Especially when the input has a long value that gets close to the clear button a link could be problematic.

Do
An input with a value must shows a clear button on the right.

Use a circular clear button with an x icon to clear the input.

Don’t
An input without a value incorrectly showing a 'clear' link on the right.

Don't use a link for clearing as this could be confused with the text inside the input.

Avoid duplication

When introducing custom qualifiers it's important to avoid repetitive icons or descriptions to increase readability and reduce noise for screen readers.

Do
An input with a value 'pinned:' suggesting 'Application', 'Form submissions', 'Performance', 'Feature requests', 'Large data sets' and 'Issues'. None of the items has an icon or additional descriptions.

An input with a value 'pinned:' suggesting 'Application', 'Form submissions', 'Performance', 'Feature requests', 'Large data sets' and 'Issues'. All items include a pin board icon and a `Pinned` description.

Don’t
An input without a value incorrectly showing a 'clear' link on the right.

Don't repeat icons or descriptions that add no additional value.

Sorting

There are two different states that should be considered when providing suggestions:

  1. Default: You've entered a matching qualifier and get default suggestions. For example: author:.
  2. Narrow down: You've entered a value after your qualifier to narrow down the suggestions. For example: author:max
Two examples of the filter input. One has the value `author:` and is suggesting a few users to pick from. The other one has the value `author:max` and is suggesting a few users with `max` in their name or username.

We should always strive to provide as relevant results as possible when dealing with user, organization, repository, issue, pull request items. This can be done through a mix of considerations:

  1. Objects you've interacted with
  2. Organizations you're part of and it's members
  3. Repositories you're part of and it's members
  4. Approximate string matching (fuzzy)

Let's take the author: as an example. While in the default state we aren't searching through the authors and want to provide a default list with users. It's crucial we make the suggestions as relevant as possible therefore we rank them based on how often/recently you've interacted with them.

Once we start narrowing down those results by using author:max we enter the narrow down state and apply approximate string matching on those suggestions. In this case we still rank users that I've recently interacted with or that are part of my organization/repositories higher.

Not all our infrastructure supports this logic yet. If not available we fall back on alphabetical ordering.

For static items that only return a handful of suggestions we often can just order items through common sense:

Two example of qualifiers that return static data. The 'created' qualifier suggests: 'Today', 'This week', 'This month', 'Oct 19, 2007', 'Before June 4, 2018' and 'After June 4, 2018'. The 'stars' qualifier suggests: 'More than 10', 'Less than 10', 'Between 10 and 100' and '100'

Qualifiers

The filter input comes with a list of predefined qualifiers and prestyled suggestions. This ensures everyone aligns on the same qualifiers as well as on the styling of suggestions.

Multiple examples of qualifiers and the suggestions they provide. Qualifiers 'language', 'author' and 'state' are used as examples.

Even though custom qualifiers can be added it's important to check if your new qualifier could fit in one of the predefined qualifiers below.

IconQualifierOriginSuggestionsFormatPreview
personassigneeapiavatar, username and Full NameusernameView
personauthorapiavatar, username and Full NameusernameView
calendarcreatedstaticToday, Yesterday, Last 7 days, Last 30 days, Oct 19, 2007, Before June 4, 2018, After June 4, 2018@today, @today-1d,@today-1w,>@today-1m, >YYYY-MM-DD, YYYY-MM-DD, YYYY-MM-DD..YYYY-MM-DDView
repo-forkedforkstaticYes, Notrue, falseView
appsisstaticAction, Code, Command, Commit...nameView
taglabelapiTitle, Description and color.titleView
codelanguagestaticC, C##, C++, CoffeeScript...languageView
globelocationstaticAmsterdam, Netherlands, Bern, Switzerland..."Amsterdam, Netherlands"View
file-badgelicensestaticBSD Zero Clause License, Academic Free License v3.0...cc0-1.0View
mentionmentionsapiavatar, username and Full Name.usernameView
organizationorgapiavatar, username and Full NameusernameView
reporepoapiavatar, username/repo-nameusername/repo-nameView
file-directorypathapipathpathView
issue-draftstate (generic)staticopen, merged, closed, draftopenView
git-pull-request-draftstate (pr)staticopen, merged, closed, draftopenView
issue-draftstate (issue)staticopen, closed, draftopenView
comment-discussioncommentsstaticMore than 10, Less than 10, Between 10 and 100, 100,>100, 10..100, 100View
peoplefollowersstaticMore than 10, Less than 10, Between 10 and 100, 100>100, 10..100, 100View
starstarsstaticMore than 10, Less than 10, Between 10 and 100, 100>100, 10..100, 100View
calendarupdatedstaticToday, Yesterday, Last 7 days, Last 30 days, Oct 19, 2007, Before June 4, 2018, After June 4, 2018@today, @today-1d,@today-1w,>@today-1m, >YYYY-MM-DD, YYYY-MM-DD, YYYY-MM-DD..YYYY-MM-DDView
file-codeextensionstaticmd, Markdown, json, JavaScript Object Notation...mdView
peopleteamapiavatars, name and total membersnameView

⚠️ This list will change a lot over the next month to accomodate different teams.

Generics

The state: qualifier has multiple variants to improve the experience for specific items:

  • state: For both pull requests and issues (no icons)
  • state-pr: For only pull requests (with icons)
  • state-issue: For only issues (with icons)

Therefore it's important to use the correct qualifier as soon as you can determine if you're filtering to pull requests or issues.

Do
An input with value 'is:pr state:' showing suggestions with colored icons: 'Open', 'Merged', 'Closed' and 'Draft'

Use the `state-pr` variant when filtering pull requests.

Don’t
An input with value 'is:pr state:' showing suggestions without icons: 'Open', 'Merged', 'Closed' and 'Draft'

Don't use the `state` variant when filtering pull requests.

Highlighting

If invalid values are used we don't show highlighting.

While this applies to all qualifiers we do understand that for the ones that depend on our api endpoints (users, repositories, organisations...) we can't always accurately match every result and therefore while not ideal we always highlight those. For example when not single signed-on to a organisation some repositories might not be returned. Also consider that users might copy paste strings containing qualifiers. In this case you need to run through every qualifier to set the highlight if needed.

Do
An input with the value 'is:bananas' where 'bananas' isn't highlighted.

Remove highlighting on values when they are invalid.

Don’t
An input with the value 'is:bananas' where 'bananas' is highlighted.

Don't show highlighting on invalid values.

No matches

When no matches are found we stop suggesting items through the popover and don't show anything. In rare cases the user could be searching for format:format within the content of items they are filtering to and this will still allow them to do so.

Do
An input with the value 'author:username-not-found'

Stop suggesting if no matches are found.

Don’t
An input with the value 'author:username-not-found' and a suggestion showing 'Not found, try a different username'

Don't show an empty state when no matches are found.

Values with spaces

Some qualifiers like location: might have values which contain spaces. eg: 'Amsterdam, Netherlands'. In this case we encapsulate the value between straight quotes (not smart quotes).

Without this it would be hard for the parser to understand where the value ends.

Do
An input with the value `location:'Amsterdam, Netherlands'` using straight quotes around the location value.

Use straight quotes around values with spaces.

Don’t
An input with the value 'location:Amsterdam, Netherlands' without using quotes around the location value. This is invalid.

Don't use values with spaces without quotes.

Deprecate where possible

There are many qualifiers on our platform that could be unified or deleted. For example type: can now be replaced by is:. Remember that deprecating means that we stop suggesting those options to users but we still keep them available in the backend until we see usage declining to low volumes.

Do
An input with the value 'is:' suggesting options: 'Issue' and 'Pull request'. The options also include icons.

Use a predefined qualifier where possible.

Don’t
An input with the value 'type:' suggesting options: 'Issue' and 'Pull request'. The options are missing icons.

Use a custom qualifier instead of a predefined one.

Formatting

Always list qualifiers in a readable way and don't include all their options by using descriptions. We do this to ensure that qualifiers are easy to scan and have enough context.

Do
An empty filter input showing initial suggestions: 'Assignee', 'Is', 'Repository', 'State' and 'Total comments'

List qualifiers in a readable way and without their options.

Don’t
An empty filter input showing initial suggestions with all the possible combinations: 'assignee: username, username', 'is: pr, issue, project', 'repo: github/github, github/primer', 'state: open, closed, draft', 'comments: >400, 100...200'

Don't list qualifiers as their raw value with possible options.

Dynamic values

Sometimes static values can be limiting when filtering results. For example, let's say you want to get all items created in the past 7 days. Using a static value, you would have to create a range of dates manually, such as 2022-01-01..2023-01-07. However, when you come back the next day (the 8th of January), you would have to update this range manually again to 2022-01-02..2023-01-08. This is not very convenient. That's why dynamic values can be useful in these situations. Using the same example, if you use the dynamic value @today-7d, you will get all items created in the past 7 days. When you come back the next day, the range of dates will automatically update to reflect the current date, so you don't have to do it manually.

ValueTranslation
@todayCurrent date (excludes time)
@meCurrent signed in user

⚠️ At the moment, we are conducting a review of dynamic values with multiple stakeholders, so changes may be made.

Options

Size

Filter inputs can have 3 different sizes:

The filter input in three different sizes. The heights are as following: 28px, 32px and 40px.
  • Small (28px)
  • Medium (32px) (default)
  • Large (40px)