SearchField

SearchField allows users to search for free-form content.

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	`({\| value: string, syntheticEvent: SyntheticEvent<HTMLInputElement>, \|}) => 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.
`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.
`onBlur`	`AbstractEventHandler<SyntheticEvent<HTMLInputElement>>`	-
`onFocus`	`({\| value: string, syntheticEvent: SyntheticEvent<HTMLInputElement>, \|}) => void`	-
`onKeyDown`	`({\| event: SyntheticKeyboardEvent<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

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.

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.

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.

function SearchFieldExample() {
    const [value, setValue] = React.useState('');

    return (
      <Flex alignItems="center" flex="grow" gap={4}>
        <Icon
          accessibilityLabel="Pinterest"
          color="red"
          icon="pinterest"
          size={20}
        />

        <Flex.Item flex="grow">
          <SearchField
            accessibilityLabel="Search all of Pinterest"
            accessibilityClearButtonLabel="Clear search field"
            id="searchFieldA11yExample"
            onChange={({value}) => setValue(value)}
            placeholder="Search and explore"
            value={value}
          />
        </Flex.Item>

        <IconButton
          accessibilityLabel="Notifications"
          icon="speech-ellipsis"
          size="md"
        />

        <IconButton accessibilityLabel="Profile" icon="person" size="md" />
      </Flex>
    );
  }

function SearchFieldExample() {
    const [value, setValue] = React.useState('');
    return (
      <Flex alignItems="center" flex="grow" gap={4}>
        <Icon
          accessibilityLabel="Pinterest"
          color="red"
          icon="pinterest"
          size={20}
        />
        <Flex.Item flex="grow">
          <SearchField
            accessibilityLabel="Search all of Pinterest"
            accessibilityClearButtonLabel="Clear search field"
            id="searchFieldA11yExample"
            onChange={({value}) => setValue(value)}
            placeholder="Search and explore"
            value={value}
          />
        </Flex.Item>
        <IconButton
          accessibilityLabel="Notifications"
          icon="speech-ellipsis"
          size="md"
        />
        <IconButton accessibilityLabel="Profile" icon="person" size="md" />
      </Flex>
    );
  }

Localization

Be sure to localize the accessibilityLabel, accessibilityClearButtonLabel, errorMessage, label and placeholder prop values. Also localize value for those cases when it can be translated.

Note that localization can lengthen text by 20 to 30 percent.

function SearchFieldExample() {
    const [value, setValue] = React.useState('');

    return (
      <Flex alignItems="center" flex="grow" gap={4}>
        <Icon
          accessibilityLabel="Pinterest"
          color="red"
          icon="pinterest"
          size={20}
        />

        <Flex.Item flex="grow">
          <SearchField
            accessibilityLabel="सभी Pinterest खोजें"
            accessibilityClearButtonLabel="खोज फ़ील्ड साफ़ करें"
            id="searchFieldLocalizationExample"
            onChange={({value}) => setValue(value)}
            placeholder="खोजें और एक्सप्लोर करें"
            value={value}
          />
        </Flex.Item>

        <IconButton
          accessibilityLabel="सूचनाएं"
          icon="speech-ellipsis"
          size="md"
        />

        <IconButton accessibilityLabel="प्रोफ़ाइल" icon="person" size="md" />
      </Flex>
    );
  }

function SearchFieldExample() {
    const [value, setValue] = React.useState('');
    return (
      <Flex alignItems="center" flex="grow" gap={4}>
        <Icon
          accessibilityLabel="Pinterest"
          color="red"
          icon="pinterest"
          size={20}
        />
        <Flex.Item flex="grow">
          <SearchField
            accessibilityLabel="सभी Pinterest खोजें"
            accessibilityClearButtonLabel="खोज फ़ील्ड साफ़ करें"
            id="searchFieldLocalizationExample"
            onChange={({value}) => setValue(value)}
            placeholder="खोजें और एक्सप्लोर करें"
            value={value}
          />
        </Flex.Item>
        <IconButton
          accessibilityLabel="सूचनाएं"
          icon="speech-ellipsis"
          size="md"
        />
        <IconButton accessibilityLabel="प्रोफ़ाइल" icon="person" size="md" />
      </Flex>
    );
  }

Variants

Visible label

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

Search Messages

function SearchFieldExample() {
  const [value, setValue] = React.useState('');

  return (
    <Flex alignItems="center" flex="grow">
      <Flex.Item flex="grow">
        <SearchField
          accessibilityLabel=""
          accessibilityClearButtonLabel="Clear search field"
          label="Search Messages"
          id="searchMessagesLabelExample"
          onChange={({value}) => setValue(value)}
          placeholder="Search by name"
          value={value}
        />
        </Flex.Item>
    </Flex>
  );
}

function SearchFieldExample() {
  const [value, setValue] = React.useState('');
  return (
    <Flex alignItems="center" flex="grow">
      <Flex.Item flex="grow">
        <SearchField
          accessibilityLabel=""
          accessibilityClearButtonLabel="Clear search field"
          label="Search Messages"
          id="searchMessagesLabelExample"
          onChange={({value}) => setValue(value)}
          placeholder="Search by name"
          value={value}
        />
        </Flex.Item>
    </Flex>
  );
}

Sizes

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

Medium (md)

Search Messages

Large (lg)

Search Messages

function SearchFieldExample() {
  const [value, setValue] = React.useState('');
  const [lgValue, setLgValue] = React.useState('');

  return (
    <Flex alignItems="center" gap={12}>
      <Flex direction="column" flex="grow" gap={4}>
        <Text>Medium (md)</Text>
        <SearchField
          accessibilityLabel=""
          accessibilityClearButtonLabel="Clear search field"
          label="Search Messages"
          id="searchMessagesMedium"
          onChange={({value}) => setValue(value)}
          placeholder="Search by name"
          value={value}
        />
      </Flex>

      <Flex direction="column" flex="grow" gap={4}>
        <Text>Large (lg)</Text>
        <SearchField
          accessibilityLabel=""
          accessibilityClearButtonLabel="Clear search field"
          label="Search Messages"
          id="searchMessagesLarge"
          onChange={({value}) => setLgValue(value)}
          placeholder="Search by name"
          value={lgValue}
          size="lg"
        />
      </Flex>
    </Flex>
  );
}

function SearchFieldExample() {
  const [value, setValue] = React.useState('');
  const [lgValue, setLgValue] = React.useState('');
  return (
    <Flex alignItems="center" gap={12}>
      <Flex direction="column" flex="grow" gap={4}>
        <Text>Medium (md)</Text>
        <SearchField
          accessibilityLabel=""
          accessibilityClearButtonLabel="Clear search field"
          label="Search Messages"
          id="searchMessagesMedium"
          onChange={({value}) => setValue(value)}
          placeholder="Search by name"
          value={value}
        />
      </Flex>
      <Flex direction="column" flex="grow" gap={4}>
        <Text>Large (lg)</Text>
        <SearchField
          accessibilityLabel=""
          accessibilityClearButtonLabel="Clear search field"
          label="Search Messages"
          id="searchMessagesLarge"
          onChange={({value}) => setLgValue(value)}
          placeholder="Search by name"
          value={lgValue}
          size="lg"
        />
      </Flex>
    </Flex>
  );
}

Error

An errorMessage can be specified if needed.

Search Messages

Invalid search term, please avoid special characters.

function SearchFieldExample() {
  const [value, setValue] = React.useState('pepper#$%');

  return (
    <Flex alignItems="center" flex="grow">
      <Flex.Item flex="grow">
        <SearchField
          accessibilityLabel=""
          accessibilityClearButtonLabel="Clear search field"
          label="Search Messages"
          id="searchMessagesError"
          onChange={({value}) => setValue(value)}
          placeholder="Search by name"
          value={value}
          errorMessage="Invalid search term, please avoid special characters."
        />
      </Flex.Item>
    </Flex>
  );
}

function SearchFieldExample() {
  const [value, setValue] = React.useState('pepper#$%');
  return (
    <Flex alignItems="center" flex="grow">
      <Flex.Item flex="grow">
        <SearchField
          accessibilityLabel=""
          accessibilityClearButtonLabel="Clear search field"
          label="Search Messages"
          id="searchMessagesError"
          onChange={({value}) => setValue(value)}
          placeholder="Search by name"
          value={value}
          errorMessage="Invalid search term, please avoid special characters."
        />
      </Flex.Item>
    </Flex>
  );
}

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

SearchField

Props

Usage guidelines

Best practices

Accessibility

Labels

Localization

Variants

Visible label

Sizes

Error

Related