SearchField

View source on GitHub
See recent changes on GitHub

SearchField allows users to search for free-form content.

also known as Search Box, Search Bar

Figma:
Ready
Responsive:
Ready
Adaptive:
N/A

Props

Component props
Name
Type
Default
accessibilityLabel
Required
string
-

String that clients such as VoiceOver will read to describe the element. Always localize the label. See the Accessibility section for more info.

id
Required
string
-

Must be unique!

onChange
Required
(arg1: {
  value: string;
  event: React.SyntheticEvent<HTMLInputElement | HTMLButtonElement>;
}) => void
-

Primary callback to handle keyboard input.

accessibilityClearButtonLabel
string
-

String that clients such as VoiceOver will read to describe the clear button element. Always localize the label. See the Accessibility section for more info.

autoComplete
"on" | "off" | "username" | "name"
-

The type of autocomplete used, if any. See MDN for more info.

dataTestId
string
-

Available for testing purposes, if needed. Consider better queries before using this prop.

errorMessage
string
-

Error text displayed below the input field.

label
string
-

Text used to label the input. Be sure to localize the text. See the Visible label variant for more info.

labelDisplay
"visible" | "hidden"
"visible"

Whether the legend should be visible or not. If hidden, the legend is still available for screen reader users, but does not appear visually. See the label visibility variant for more info.

onBlur
(arg1: { event: React.FocusEvent<HTMLInputElement>; value: string }) => void
-
onFocus
(arg1: { value: string; event: React.FocusEvent<HTMLInputElement> }) => void
-
onKeyDown
(arg1: { event: React.KeyboardEvent<HTMLInputElement>; value: string }) => void
-

Secondary callback for keyboard events. Possible uses include validation, form submission, etc.

placeholder
string
-

Text displayed before the user has entered anything.

ref
HTMLDivElement | HTMLAnchorElement
-

Ref that is forwarded to the underlying input element.

size
"md" | "lg"
"md"

md: 40px, lg: 48px

value
string
-

The current value of the input.

Usage guidelines

When to use
  • To search or filter content within a surface.
When not to use
  • As a means of inputting content to a form. Use TextField instead.
  • To act as an auto-complete input. Use ComboBox instead.

Best practices

Do

Place SearchField above the content the user will be searching.

Don't

Hide SearchField behind an IconButton if there is enough space for the full component.

Do

Make the placeholder specific. Give the user a hint about the content they're searching and/or what parameters they can use to search.

Don't

Add critical information to the placeholder. The placeholder text disappears once the user begins entering data and will therefore be unavailable.

Do

Make sure SearchField is displayed wide enough to completely display common search terms.

Don't

Truncate or wrap text within SearchField.

Accessibility

Labels

SearchField should ideally have a visible label above the input using the label prop. However, if need be, accessibilityLabel can be used to provide screen readers with context about the SearchField.

Be sure to also specify (and localize) a string for the accessibilityClearButtonLabel.

import { useState } from 'react';
import { Box, SearchField } from 'gestalt';

export default function SearchFieldExample() {
  const [searchValue, setSearchValue] = useState('');
  return (
    <Box height="100%" padding={4} width="100%">
      <SearchField
        accessibilityClearButtonLabel="Clear search field"
        accessibilityLabel="Search all of Pinterest"
        id="searchFieldA11yExample"
        onChange={({ value }) => setSearchValue(value)}
        placeholder="Search and explore"
        value={searchValue}
      />
    </Box>
  );
}

Localization

Be sure to localize all text strings. Note that localization can lengthen text by 20 to 30 percent.

Also localize value for those cases when it can be translated. 

import { useState } from 'react';
import { Box, SearchField } from 'gestalt';

export default function SearchFieldExample() {
  const [searchValue, setSearchValue] = useState('');
  return (
    <Box height="100%" padding={4} width="100%">
      <SearchField
        accessibilityClearButtonLabel="खोज फ़ील्ड साफ़ करें"
        accessibilityLabel="सभी Pinterest खोजें"
        id="searchFieldLocalizationExample"
        onChange={({ value }) => setSearchValue(value)}
        placeholder="खोजें और एक्सप्लोर करें"
        value={searchValue}
      />
    </Box>
  );
}

Variants

Visible label

When specified, label adds a label above the SearchField. If label is specified, accessibilityLabel can be an empty string.

import { useState } from 'react';
import { Box, SearchField } from 'gestalt';

export default function SearchFieldExample() {
  const [searchValue, setSearchValue] = useState('');
  return (
    <Box height="100%" padding={4} width="100%">
      <SearchField
        accessibilityClearButtonLabel="Clear search field"
        accessibilityLabel=""
        id="searchMessagesLabelExample"
        label="Search Messages"
        onChange={({ value }) => setSearchValue(value)}
        placeholder="Search by name"
        value={searchValue}
      />
    </Box>
  );
}

Sizes

There are 2 sizes available: md (default) and lg.

import { useState } from 'react';
import { Box, Flex, SearchField } from 'gestalt';

export default function SearchFieldExample() {
  const [searchValue, setSearchValue] = useState('');
  const [lgValue, setLgValue] = useState('');

  return (
    <Box padding={8} width="100%">
      <Flex direction="column" gap={6} width="100%">
        <SearchField
          accessibilityClearButtonLabel="Clear search field"
          accessibilityLabel=""
          id="searchfield_size_md_label"
          onChange={({ value }) => setSearchValue(value)}
          placeholder="md size placeholder"
          size="md"
          value={searchValue}
        />
        <SearchField
          accessibilityClearButtonLabel="Clear search field"
          accessibilityLabel=""
          id="searchfield_size_lg_label"
          onChange={({ value }) => setLgValue(value)}
          placeholder="lg size placeholder"
          size="lg"
          value={lgValue}
        />
        <SearchField
          accessibilityClearButtonLabel="Clear search field"
          accessibilityLabel=""
          id="searchfield_size_md_nolabel"
          label="md size label"
          onChange={({ value }) => setSearchValue(value)}
          placeholder="Size md"
          size="md"
          value={searchValue}
        />
        <SearchField
          accessibilityClearButtonLabel="Clear search field"
          accessibilityLabel=""
          id="searchfield_size_lg_nolabel"
          label="lg size label"
          onChange={({ value }) => setLgValue(value)}
          placeholder="Size lg"
          size="lg"
          value={lgValue}
        />
      </Flex>
    </Box>
  );
}

Error

An errorMessage can be specified if needed.

import { useState } from 'react';
import { Box, Flex, SearchField } from 'gestalt';

export default function SearchFieldExample() {
  const [searchValue, setSearchValue] = useState('pepper#$%');

  return (
    <Box padding={8} width="100%">
      <Flex direction="column" gap={6} width="100%">
        <SearchField
          accessibilityClearButtonLabel="Clear search field"
          accessibilityLabel=""
          errorMessage="Invalid search term, please avoid special characters."
          id="searchMessagesError"
          label="Search Messages"
          onChange={({ value }) => setSearchValue(value)}
          placeholder="Search by name"
          size="md"
          value={searchValue}
        />
        <SearchField
          accessibilityClearButtonLabel="Clear search field"
          accessibilityLabel=""
          errorMessage="Invalid search term, please avoid special characters."
          id="searchMessagesError"
          label="Search Messages"
          onChange={({ value }) => setSearchValue(value)}
          placeholder="Search by name"
          size="lg"
          value={searchValue}
        />
      </Flex>
    </Box>
  );
}

Component quality checklist

Component quality checklist
Quality item
Status
Status description
Figma Library
Ready
Component is available in Figma for web and mobile web.
Responsive Web
Ready
Component responds to changing viewport sizes in web and mobile web.

ComboBox
ComboBox allows users to filter a list when selecting an option. Choose ComboBox when the user is selecting from a finite list of options.
TextField
TextField provides an affordance to input small to medium length text. Unless the text is used to search for or filter through content, choose TextField for shorter text input.
TextArea
TextArea allows for multiline text input, suitable for longer length text. Unless the text is used to search for or filter through content, choose TextArea for longer text input.

Edit page on GitHub