SearchField

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`	-
`onChange` Required	`({ value: string, syntheticEvent: SyntheticEvent<HTMLInputElement> }) => void`	-
`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"`	-
`errorMessage`	`string`	-
`label`	`string`	-
	Text used to label this search field. Should be localized. See the Visible label variant for more info.
`onBlur`	`({ event: SyntheticEvent<HTMLInputElement> }) => void`	-
`onFocus`	`({ value: string, syntheticEvent: SyntheticEvent<HTMLInputElement> }) => void`	-
`onKeyDown`	`({ event: SyntheticKeyboardEvent<HTMLInputElement>, value: string }) => void`	-
	Callback for key stroke events.
`placeholder`	`string`	-
`ref`	`React.Ref<"input">`	-
	Forward the ref to the underlying input element
`size`	`"md" \| "lg"`	`"md"`
	md: 40px, lg: 48px
`value`	`string`	-

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.

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 this SearchField.

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

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

    return (
      <Flex gap={4} alignItems="center" flex="grow">
        <Icon
          icon="pinterest"
          color="red"
          size={20}
          accessibilityLabel="Pinterest"
        />
        <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 gap={4} alignItems="center" flex="grow">
        <Icon
          icon="pinterest"
          color="red"
          size={20}
          accessibilityLabel="Pinterest"
        />
        <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>
    );
  }

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 gap={8} alignItems="center">
      <Flex gap={4} direction="column" flex="grow">
        <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 gap={4} direction="column" flex="grow">
        <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 gap={8} alignItems="center">
      <Flex gap={4} direction="column" flex="grow">
        <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 gap={4} direction="column" flex="grow">
        <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 flex="grow" alignItems="center">
      <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 flex="grow" alignItems="center">
      <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>
  );
}

Edit page on GitHub