Search Input

Input field for search queries.

UsageGuidelinesAPI

Use Search Input...

For page search query.

Don't use Search Input...

If you need our default Search Input with options: use Combobox with Search Input instead.

<StandardForm>
  <FormField>
    <FormLabel visuallyHidden>My SearchInput</FormLabel>
    <SearchInput
      placeholder="Search"
      accessibleTextForClearButton="Clear"
      accessibleTextForSearchButton="Search"
    />
  </FormField>
</StandardForm>

<StandardForm>
  <FormField>
    <FormLabel visuallyHidden>My SearchInput</FormLabel>
    <SearchInput
      placeholder="Search"
      accessibleTextForClearButton="Clear"
      accessibleTextForSearchButton="Search"
    />
  </FormField>
</StandardForm>

Managing state

As is the case with most form elements, folks often want to "control" this component. Controlling a component means that you take ownership over its state rather than letting the browser manage the state for you. When you control a component, you own the source of truth for the UI. This means that you don't need to query the DOM in order to determine the current value of the element. So, when it comes time to use the value of the element somewhere else (e.g. submitting the selection to a back-end service) you can trust your stored value.

To control a SearchInput, store the selected value (e.g., in React state or a Redux store) and provide a handler to update this value when users interact with the component.

() => {
  const [value, setValue] = React.useState('')
  return (
    <FormField>
      <FormLabel visuallyHidden>My SearchInput</FormLabel>
      <SearchInput
        placeholder="Search"
        accessibleTextForClearButton="Clear"
        accessibleTextForSearchButton="Search"
        value={value}
        onChange={e => setValue(e.target.value)}
        onClear={() => setValue('')}
      />
    </FormField>
  )
}

() => {
  const [value, setValue] = React.useState('')
  return (
    <FormField>
      <FormLabel visuallyHidden>My SearchInput</FormLabel>
      <SearchInput
        placeholder="Search"
        accessibleTextForClearButton="Clear"
        accessibleTextForSearchButton="Search"
        value={value}
        onChange={e => setValue(e.target.value)}
        onClear={() => setValue('')}
      />
    </FormField>
  )
}

If you don't need to manage the state of the SearchInput, you can omit the value and onChange props, allowing the browser to handle the state. Consider using the defaultValue prop to specify the initial selected value and wrapping inside of a StandardForm to handle the onSubmit.

Accessibility

Provide assistive devices with information on what the input field does. You can either:

Use an aria-label attribute with a localized value.
Wrap the Search Input into a FormField with a FormLabel component with the visuallyHidden prop. Refer to Form

Provide assistive devices with information on what the buttons do for the Search and Clear icon buttons that are simply icons and have no visible text. For react users, the following props are required: accessibleTextForClearButton and accessibleTextForSearchButton.

Implementation

Avoid placing a Search Input inside an element that is a table cell or has CSS display: table-cell. This configuration may result in the Search Input being rendered more narrowly than its actual minimum width. Use Grid to constrain it instead.

Anatomy

For local search instances, consider including an on-page label to:

Help make the function of the searchbar more evident.
Provide additional context to the interaction.

If an on-page label is included, consider using the searchbar placeholder text to provide additional helpful instructions.

Content accessibility

AA (required)

AAA (advised)

If search instance includes an on-page label:

Position label immediately before field

Content identity (editorial)

Ensure all content adheres to our global copy style guide standards.

Content usability

Make sure wording is specific, instructional and contextual.
Use <verb> + <noun> sentence structure for label and button text
- See Language section for more information.

Representative examples:

<GridContainer>
  <Row>
    <Column span={6}>
      <H4 mb={5}>Do not</H4>
      <StandardForm>
        <FormField>
          <FormLabel visuallyHidden>Search</FormLabel>
          <FormInputGroup>
            <SearchInput
              placeholder="Search"
              accessibleTextForClearButton="Clear"
              accessibleTextForSearchButton="Search"
            />
          </FormInputGroup>
        </FormField>
      </StandardForm>
      <Box>
        <H3>Standard Business Cards</H3>
        <P>
          <RatingsStars
            ratingValue={4.5}
            aria-label="Rating: 4.5 out of 5 stars"
          />{' '}
          4.3 <Link href="#">11 254 Reviews</Link>
        </P>
        <StandardForm>
          <FormField>
            <FormLabel visuallyHidden>Designs</FormLabel>
            <FormInputGroup>
              <SearchInput
                placeholder="Designs"
                accessibleTextForClearButton="Clear"
                accessibleTextForSearchButton="Search"
              />
            </FormInputGroup>
          </FormField>
        </StandardForm>
      </Box>
    </Column>
    <Column span={6}>
      <H4 mb={5}>Do</H4>
      <P py={{ xs: 1, md: 1, lg: 3, xl: 4 }}>
        &lt;Search&gt; &lt;all products and design services&gt;
      </P>
      <P pt={{ xs: 1, md: 1, lg: 11, xl: 12 }}>
        &lt;Search&gt; &lt;business card features&gt;
      </P>
    </Column>
  </Row>
</GridContainer>

<GridContainer>
  <Row>
    <Column span={6}>
      <H4 mb={5}>Do not</H4>
      <StandardForm>
        <FormField>
          <FormLabel visuallyHidden>Search</FormLabel>
          <FormInputGroup>
            <SearchInput
              placeholder="Search"
              accessibleTextForClearButton="Clear"
              accessibleTextForSearchButton="Search"
            />
          </FormInputGroup>
        </FormField>
      </StandardForm>
      <Box>
        <H3>Standard Business Cards</H3>
        <P>
          <RatingsStars
            ratingValue={4.5}
            aria-label="Rating: 4.5 out of 5 stars"
          />{' '}
          4.3 <Link href="#">11 254 Reviews</Link>
        </P>
        <StandardForm>
          <FormField>
            <FormLabel visuallyHidden>Designs</FormLabel>
            <FormInputGroup>
              <SearchInput
                placeholder="Designs"
                accessibleTextForClearButton="Clear"
                accessibleTextForSearchButton="Search"
              />
            </FormInputGroup>
          </FormField>
        </StandardForm>
      </Box>
    </Column>
    <Column span={6}>
      <H4 mb={5}>Do</H4>
      <P py={{ xs: 1, md: 1, lg: 3, xl: 4 }}>
        &lt;Search&gt; &lt;all products and design services&gt;
      </P>
      <P pt={{ xs: 1, md: 1, lg: 11, xl: 12 }}>
        &lt;Search&gt; &lt;business card features&gt;
      </P>
    </Column>
  </Row>
</GridContainer>

Language

Label/placeholder text

Verb should always be ‘search’.
Noun phrase should be specific to the search context (global or local).

Representative examples:

Verb	Noun
Search	t shirts
Search	your order history
Search	help articles
Search	logo ideas
Search	gallery templates

Localization

Use plain English to help ensure source language is easy and efficient to translate.
Remember to allow for text expansions for other languages - roughly 35%.

SEO

All internal searches made through the global site search bar are non-indexable which means they are not available for Google to use in its search results. As long as that rule remains in place any change on how internal searches are made and/or results are displayed won't have any effect on our SEO.

Props

SearchInput

This component is implemented using the <input /> as the root element. You can utilize the native attributes supported by <input /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.

See core props for additional props that can be applied to this component.

prop	type	required	description	default
skin	`"standard" \| "error" \| null`	false	The visual variant. Note that error is implied if the SearchInput is used inside of a FormInput that also contains a FormError. Available options: 'standard', 'error'	null
onClear	`((...args: any[]) => any) \| null`	false	The click handler for the clear button	null
onSearchSubmit	`((...args: any[]) => any) \| null`	false	The click handler for the search button	null
accessibleTextForClearButton	`string`	true	-	null
accessibleTextForSearchButton	`string`	true	-	null

Search Input

Use Search Input...

Don't use Search Input...

Managing state

Accessibility

Implementation

Anatomy

Content accessibility

AA (required)

AAA (advised)

Content identity (editorial)

Content usability

Language

Label/placeholder text

Localization

SEO

Props

Related