# List component for Stripe Apps

Display a list of information in a variety of preconfigured formats.

# v8

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

To add the `List` component to your app:

```js
import {List, ListItem} from '@stripe/ui-extension-sdk/ui';
```

You can use the `onAction` handler to respond to `press` events on list items.

### List props

| Property   | Type                                                                                                                                                 |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children` | (Required)
  `React.ReactNode`

  One or more `ListItem` components.                                                                                 |
| `onAction` | (Optional)
  `((id: React.Key) => void) | undefined`

  Press event handler which receives the corresponding key of the `ListItem` that was pressed. |

## List items

Every list is made up of a collection of `ListItem` components. Uniquely identify each list item using the `key` prop.

### ListItem props

| Property         | Type                                                                                                                                               |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `icon`           | (Optional)
  `React.ReactNode`

  Icon that appears to the left of the content and description. Will be overridden by `image` if both are present. |
| `id`             | (Optional)
  `string | undefined`

  The id of the item. This will be passed into the `onAction` handler of `List`.                                |
| `image`          | (Optional)
  `React.ReactNode`

  Image that appears to the left of the content and description. Will override `icon` if both are present.         |
| `secondaryTitle` | (Optional)
  `React.ReactNode`

  Secondary content for the `ListItem` component.                                                                  |
| `size`           | (Optional)
  `("default" | "large") | undefined`

  Size of the `ListItem` component.                                                              |
| `title`          | (Optional)
  `React.ReactNode`

  Title content for the `ListItem` component.                                                                      |
| `value`          | (Optional)
  `React.ReactNode`

  The value to display on the right-hand side of the item.                                                         |

## Secondary title

You can add a secondary title to a list item using the `secondaryTitle` property.

## Values

The `ListItem` `value` prop can take arbitrary JSX.

### Unsupported components

Note that certain interactive components **won’t** work as `value` props in a `ListItem`:

- [Select](https://docs.stripe.com/stripe-apps/components/select.md)
- [TextArea](https://docs.stripe.com/stripe-apps/components/textarea.md)
- [TextField](https://docs.stripe.com/stripe-apps/components/textfield.md)


# v9

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

To add the `List` component to your app:

```js
import {List, ListItem} from '@stripe/ui-extension-sdk/ui';
```

You can use the `onAction` handler to respond to `press` events on list items.

### List props

| Property   | Type                                                                                                                                                 |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children` | (Required)
  `React.ReactNode`

  One or more `ListItem` components.                                                                                 |
| `onAction` | (Optional)
  `((id: React.Key) => void) | undefined`

  Press event handler which receives the corresponding key of the `ListItem` that was pressed. |

## List items

Every list is made up of a collection of `ListItem` components. Uniquely identify each list item using the `key` prop.

### ListItem props

| Property         | Type                                                                                                                                               |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `icon`           | (Optional)
  `React.ReactNode`

  Icon that appears to the left of the content and description. Will be overridden by `image` if both are present. |
| `id`             | (Optional)
  `string | undefined`

  The id of the item. This will be passed into the `onAction` handler of `List`.                                |
| `image`          | (Optional)
  `React.ReactNode`

  Image that appears to the left of the content and description. Will override `icon` if both are present.         |
| `secondaryTitle` | (Optional)
  `React.ReactNode`

  Secondary content for the `ListItem` component.                                                                  |
| `size`           | (Optional)
  `("default" | "large") | undefined`

  Size of the `ListItem` component.                                                              |
| `title`          | (Optional)
  `React.ReactNode`

  Title content for the `ListItem` component.                                                                      |
| `value`          | (Optional)
  `React.ReactNode`

  The value to display on the right-hand side of the item.                                                         |

## Secondary title

You can add a secondary title to a list item using the `secondaryTitle` property.

## Values

The `ListItem` `value` prop can take arbitrary JSX.

### Unsupported components

Note that certain interactive components **won’t** work as `value` props in a `ListItem`:

- [Select](https://docs.stripe.com/stripe-apps/components/select.md)
- [TextArea](https://docs.stripe.com/stripe-apps/components/textarea.md)
- [TextField](https://docs.stripe.com/stripe-apps/components/textfield.md)


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