# React Native SearchField

> A React Native search bar for iOS, Android and the web: iOS's gray search field with Cancel, Material 3's search pill, or an outlined web input, with a clear button and the keyboard's Search key.

# 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.

```tsx
import { SearchField } from 'patine-ui';
```

```tsx live
import { List, ListItem, SearchField, Text, VStack } from 'patine-ui';

const CONTACTS = ['Ana Lucía Pérez', 'Daniel Okafor', 'Maya Cohen', 'Noah Kim', 'Priya Raman', 'Sven Larsen'];

export default function Example() {
  const [query, setQuery] = React.useState('');
  const matches = CONTACTS.filter((name) => name.toLowerCase().includes(query.trim().toLowerCase()));
  return (
    <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>
  );
}
```

## 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.

```tsx live
import { useState } from 'react';
import { Button, HStack, List, ListItem, SearchField, Text, VStack } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

const PRODUCTS = ['Linen shirt', 'Linen trousers', 'Canvas tote', 'Wool beanie', 'Wool socks', 'Leather belt', 'Rain jacket', 'Running shoes'];

export default function Example() {
  const [query, setQuery] = useState('');
  const [recent, setRecent] = useState(['rain jacket', 'socks']);
  const q = query.trim().toLowerCase();
  const hits = PRODUCTS.filter((p) => p.toLowerCase().includes(q));
  const remember = (term: string) => term.trim() && setRecent((r) => [term.trim().toLowerCase(), ...r.filter((x) => x !== term.trim().toLowerCase())].slice(0, 5));
  return (
    <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.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | — | Controlled text. |
| `defaultValue` | `string` | `''` | 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. |
| `placeholder` | `string` | `'Search'` | The hint, and the field's name for screen readers. |
| `disabled` | `boolean` | `false` | Dims it and blocks typing. |
| `autoFocus` | `boolean` | `false` | Focuses it on mount. |
| `labels` | `{ clear, cancel }` | `'Clear search'`, `'Cancel'` | The buttons' text, for translation. |
| `style` | `StyleProp<ViewStyle>` | — | The row around the field. |
| `inputStyle` | `StyleProp<TextStyle>` | — | The input itself. |
| `theme`, `design` | | | As every component. |
