Search

Search patterns enable users to find certain information by adding criteria that match their query.

Examples

<script>
export default {
  data() {
    return {
      historyItems: ['author:@admin', 'assignee:@admin milestone:%12.5', 'label:~test'],
    };
  },
  methods: {
    clearHistory() {
      this.historyItems = [];
    },
  },
};
</script>

<template>
  <gl-search-box-by-click :history-items="historyItems" @clear-history="clearHistory" />
</template>
<script>
export default {
  data() {
    return {
      searchQuery: '',
    };
  },
};
</script>

<template>
  <gl-search-box-by-type v-model="searchQuery" placeholder="Search" />
</template>

View in Pajamas UI Kit →

Structure

TODO:
Add structure image. Create an issue

Guidelines

When to use

TODO:
Add when to use. Create an issue

When not to use

TODO:
Add when not to use. Create an issue

Variants

  1. Search by typing: This pattern doesn't use a button to trigger the search. When users start typing the search action triggers after a short delay. In order to communicate that a search is being performed, a spinner is added in the right corner of the search box. A magnifying glass icon is placed in the left corner of the search box to indicate to the user that the input is a search field. Narrowing down a large list of results as a user types can create performance issues. Consider using the Search by confirmation pattern below if performance is a concern.
  2. Search by confirmation: This pattern is visually different from the one above because users interact with it differently. The magnifying glass icon is placed inside the button which triggers the search action. The presence of the button indicates the need for confirmation to trigger the search. Enter also triggers the action. A dropdown containing search history is commonly used as an addition to the search by confirmation pattern.

Appearance

It’s a common practice to place the search box on the top right of the page — it’s where Internet users learned to expect it. When the search box is a simple search or filter, it should be positioned on the top right in the layout, and limited in width. More complex search boxes can be wider and positioned elsewhere.

Placeholder

  • The placeholder in a search box should ideally be just Search because it should be clear what the user is searching through from the placement of the search box on the page. For example, a search box placed under a title Labels searches through labels. If that’s not possible, a more specific Search labels placeholder can be used. The search patterns are one of those exceptions where the input field labels aren’t present at all. Because of that, a placeholder should always be there to clearly indicate to users that this is a search box.
  • Do not use ellipsis (…) in the placeholder unless it’s truncated or the text is incomplete (see Punctuation). For example, Search or Search labels do not need an ellipsis, but Search and jump to… uses one because the text is incomplete.
  • Even though the search patterns can be used for either filtering or searching for information, always try to use the word Search for the placeholder. This is another small detail that makes the pattern easier to recognize. As an exception, it’s OK to use another word if it makes the interaction and the experience clearer.

Behavior

Search by typing variant uses delayed feedback to reduce the server load. Use a faster debounce period when possible to make search results feel quick and responsive.

Content

While search results aren't part of the component itself, the Empty States page has additional guidance on what to display if the search returns no results.

Code reference

GlSearchBoxByClick

import { GlSearchBoxByClick } from '@gitlab/ui';

Props

Name
Description
Default

value

string If provided, used as value of search input

''

historyItems

array If provided, used as history items for this component

null

placeholder

string If provided, used as a placeholder for this component

'Search'

clearable

boolean When true, shows a clear button to reset the search.

true

disabled

boolean If provided and true, disables the input and controls

false

recentSearchesHeader

string i18n for recent searches title within history dropdown

'Recent searches'

clearButtonTitle

string i18n for clear button title

'Clear'

closeButtonTitle

string i18n for close button title within history dropdown

'Close'

clearRecentSearchesText

string i18n for recent searches clear text

'Clear recent searches'

noRecentSearchesText

string Text displayed when there are no recent searches.

"You don't have any recent searches"

tooltipContainer

boolean Container for tooltip. Valid values: DOM node, selector string or `false` for default

false

searchButtonAttributes

object HTML attributes to add to the search button

{}

showSearchButton

boolean Display search button to perform a search. Note: it is required to ensure accessibility for WCAG 2.1 3.2.2: On Input. If the search button is hidden, a separate button should be provided for the same context.

true

wrapperAttributes

object HTML attributes to apply to the wrapper element.

{}

Slots

Name
Description
history-item

Slot to customize history item in history dropdown. Used only with history-items prop

input

Events

Name
Description
input

undefined

submit

undefined Emitted when search is submitted

history-item-selected

undefined Emitted when item from history is selected

clear

Emitted when search is cleared

clear-history

Emitted when clear history button is clicked

GlSearchBoxByType

import { GlSearchBoxByType } from '@gitlab/ui';

Props

Name
Description
Default

v-model

string If provided, used as value of search input

''

borderless

boolean Whether to render the search box without borders

false

clearButtonTitle

string Title text for the clear button

() => translate('GlSearchBoxByType.clearButtonTitle', 'Clear')

disabled

boolean If provided and true, disables the input and controls

false

isLoading

boolean Puts search box into loading state, rendering spinner

false

tooltipContainer

boolean Container for tooltip. Valid values: DOM node, selector string or `false` for default

false

Events

Name
Description
input

undefined Emitted when the input value changes or gets cleared.

focusout

undefined Emitted when focus leaves the search box (input and clear button).

focusin

undefined Emitted when focus enters the search box (input or clear button).

Last updated at: 

Morty Proxy This is a proxified and sanitized view of the page, visit original site.