Skip to main content

SearchField

A search box drawn as each platform draws its own: iOS's short gray search bar, Material 3's pill, an outlined input on the web. It has a magnifier, a clear button while there's text, the keyboard's Search key, and an optional iOS-style Cancel.

import { SearchField } from 'patine-ui';
Loading…
<VStack gap="sm" style={{ width: 340 }}>
  <SearchField value={query} onValueChange={setQuery} placeholder="Search contacts" onCancel={() => {}} />
  <List>
    {matches.map((name) => (
      <ListItem key={name} title={name} onPress={() => {}} />
    ))}
  </List>
  {matches.length === 0 ? <Text color="textSecondary">No contacts match “{query}”.</Text> : null}
</VStack>

Try the props​

Props
placeholder
onCancel
design
<SearchField value={query} onValueChange={setQuery} />

Example: recent searches​

A shop's search screen: with the field empty it lists your recent searches, a search adds to them, and typing filters the catalog as you go.

Loading…
<VStack gap="sm" style={{ width: '100%', maxWidth: 400 }}>
  <SearchField value={query} onValueChange={setQuery} onSubmit={remember} onCancel={() => setQuery('')} placeholder="Search the shop" />
  {q ? (
    <List>
      {hits.map((name) => (
        <ListItem key={name} title={name} onPress={() => remember(query)} />
      ))}
      {hits.length ? null : <ListItem title={`No products match “${query}”`} showChevron={false} disabled />}
    </List>
  ) : recent.length ? (
    <List title="Recent">
      {recent.map((term) => (
        <ListItem key={term} leading={<Icon name="history" size="sm" />} title={term} onPress={() => setQuery(term)} />
      ))}
    </List>
  ) : (
    <Text color="textSecondary">Your searches show up here.</Text>
  )}
  {!q && recent.length ? (
    <HStack justify="flex-end">
      <Button size="sm" variant="ghost" onPress={() => setRecent([])}>Clear history</Button>
    </HStack>
  ) : null}
</VStack>

Search on submit​

onValueChange fires on every keystroke, for filtering a list as the user types. For a search that goes to a server, use onSubmit, which gets the text when the user presses the keyboard's Search key or Enter.

Cancel​

Give onCancel and a Cancel button shows beside the field while it has focus, as on iOS. Pressing it clears the text, closes the keyboard and calls onCancel, so you can leave search mode.

Designs​

  • brand: an outlined 44pt field with a focus ring.
  • iOS: a 36pt gray field with rounded corners, no border.
  • Material 3: a 48pt pill on a tonal fill, as its search bar.
  • web: a 38pt outlined input with a focus ring.

Accessibility​

  • The field is named by its placeholder, or accessibilityLabel. The clear and Cancel buttons are named, and the clear button's touch area reaches 44pt.
  • The keyboard shows a Search key. On the web, Up and Down arrow keys pass from the field to a list of results below it.

Props​

Other TextInput props pass through.

PropTypeDefaultDescription
valuestring—Controlled text.
defaultValuestring''Initial text when uncontrolled.
onValueChange(text: string) => void—Called as the user types or clears.
onSubmit(text: string) => void—Called on the keyboard's Search key or Enter.
onCancel() => void—Shows Cancel while focused; called after it clears the text.
placeholderstring'Search'The hint, and the field's name for screen readers.
disabledbooleanfalseDims it and blocks typing.
autoFocusbooleanfalseFocuses it on mount.
labels{ clear, cancel }'Clear search', 'Cancel'The buttons' text, for translation.
styleStyleProp<ViewStyle>—The row around the field.
inputStyleStyleProp<TextStyle>—The input itself.
theme, designAs every component.