# SearchField component for Stripe Apps

Use SearchField to allow users to search and filter content in your Stripe app.

# v8

> This is a v8 for when app-sdk-version is 8. View the full page at https://docs.stripe.com/stripe-apps/components/searchfield?app-sdk-version=8.

The `SearchField` component isn’t available in the selected SDK version.


# v9

> This is a v9 for when app-sdk-version is 9. View the full page at https://docs.stripe.com/stripe-apps/components/searchfield?app-sdk-version=9.

To add the `SearchField` component to your app:

```js
import {SearchField} from '@stripe/ui-extension-sdk/ui';
```

Use `SearchField` to help users search and pick one or more values from a list. Use it when the list is long, filterable, or dynamically loaded.

#### Single selection

### SingleSearchFieldProps props

| Property            | Type                                                                                                                                                                                                                                |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`              | (Required)
  `SearchFieldDataObject[]`

  Array of data items to render in the SearchField results.

  Related types: [SearchFieldDataObject](https://docs.stripe.com/stripe-apps/components/searchfield.md#searchfielddataobject). |
| `label`             | (Required)
  `string`

  Text that describes the control. It’s visible and clickable.                                                                                                                                               |
| `selectionMode`     | (Required)
  `"single"`                                                                                                                                                                                                             |
| `defaultSelected`   | (Optional)
  `(string | number) | undefined`

  Initial selected key in the collection.                                                                                                                                             |
| `description`       | (Optional)
  `string | undefined`

  Descriptive text rendered adjacent to the control’s label.                                                                                                                                     |
| `disabled`          | (Optional)
  `boolean | undefined`

  Marks the field as disabled and affects its visual appearance.                                                                                                                                |
| `error`             | (Optional)
  `string | undefined`

  Error text rendered below the control.                                                                                                                                                         |
| `onSelectionChange` | (Optional)
  `((key: string | number) => void) | undefined`

  Handler called when the selection changes for single-selection fields.                                                                                               |
| `placeholder`       | (Optional)
  `string | undefined`

  Text shown in the input when it has no value.                                                                                                                                                  |

### SearchFieldDataObject

| Property | Type                  |
| -------- | --------------------- |
| `id`     | (Required)
  `string` |
| `value`  | (Required)
  `string` |

#### Multiple selection

### MultiSearchFieldProps props

| Property            | Type                                                                                                                                                                                                                                |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`              | (Required)
  `SearchFieldDataObject[]`

  Array of data items to render in the SearchField results.

  Related types: [SearchFieldDataObject](https://docs.stripe.com/stripe-apps/components/searchfield.md#searchfielddataobject). |
| `label`             | (Required)
  `string`

  Text that describes the control. It’s visible and clickable.                                                                                                                                               |
| `selectionMode`     | (Required)
  `"multiple"`                                                                                                                                                                                                           |
| `defaultSelected`   | (Optional)
  `(string | number)[] | undefined`

  Initial selected keys in the collection.                                                                                                                                          |
| `description`       | (Optional)
  `string | undefined`

  Descriptive text rendered adjacent to the control’s label.                                                                                                                                     |
| `disabled`          | (Optional)
  `boolean | undefined`

  Marks the field as disabled and affects its visual appearance.                                                                                                                                |
| `error`             | (Optional)
  `string | undefined`

  Error text rendered below the control.                                                                                                                                                         |
| `onSelectionChange` | (Optional)
  `((keys: Set<string | number>) => void) | undefined`

  Handler called when the selection changes for multiple-selection fields.                                                                                       |
| `placeholder`       | (Optional)
  `string | undefined`

  Text shown in the input when it has no value.                                                                                                                                                  |

### SearchFieldDataObject

| Property | Type                  |
| -------- | --------------------- |
| `id`     | (Required)
  `string` |
| `value`  | (Required)
  `string` |

## More examples

### Disabled

### Description

### Error

### Placeholder


## See also

- [Design patterns to follow](https://docs.stripe.com/stripe-apps/patterns.md)
- [Style your app](https://docs.stripe.com/stripe-apps/style.md)
- [UI testing](https://docs.stripe.com/stripe-apps/ui-testing.md)