---
name: List
menu: 'Components: Layouts'
route: /components/layout/list
---

# List

import {
  Playground,
  Props,
} from 'docz'
import { Placeholder } from '../../../../docs/_components/Placeholder/Placeholder'
import { List } from './List'
import { ListItem } from './ListItem'

The List aligns content into an organized list.

## Basic Usage

To implement the List component, you need to import it first:

```js
import { List, ListItem } from '@react-ui-org/react-ui';
```

And use it:

<Playground>
  <List>
    <ListItem>
      <Placeholder bordered>List item</Placeholder>
    </ListItem>
    <ListItem>
      <Placeholder bordered>List item</Placeholder>
    </ListItem>
    <ListItem>
      <Placeholder bordered>List item</Placeholder>
    </ListItem>
  </List>
</Playground>

See [API](#api) for all available options.

## General Guidelines

- **Wrap your items** into the [ListItem](#listitem) component. This ensures
  your content is properly spaced and aligned with other List elements. Do
  **not** try to put any custom HTML or React components directly into the
  List layout without wrapping it with the ListItem first.

- For forms, use rather the [FormLayout](/components/layout/form-layout)
  component which is designed specifically for that purpose.

## List Alignment

You can simply set the list alignment by specifying the `align` option.

👉 At the current stage of development, React UI is **RTL aware** so switching
to a fully RTL-compatible behavior in the future should be painless. That's why
the alignment values are called rather `start` than `left` and `end` instead of
`right`.

<Playground>
  <List align="end">
    <ListItem>
      <Placeholder bordered>List item</Placeholder>
    </ListItem>
    <ListItem>
      <Placeholder bordered>List item</Placeholder>
    </ListItem>
    <ListItem>
      <Placeholder bordered>List item</Placeholder>
    </ListItem>
  </List>
</Playground>

## Auto Width

For cases when you prefer the list items to keep their original width and don't
want them to expand over the full width of the parent of the list, there is the
`autoWidth` option. It **shrinks the list according to its longest item.**
However, the root div always behaves as a full-width block element (unless you
put it inside a flex or grid layout).

<Playground>
  <List align="end" autoWidth>
    <ListItem>
      <Placeholder bordered>List item</Placeholder>
    </ListItem>
    <ListItem>
      <Placeholder bordered>List item that is longer</Placeholder>
    </ListItem>
    <ListItem>
      <Placeholder bordered>List item that is even a bit longer</Placeholder>
    </ListItem>
  </List>
</Playground>

## API

<Props of={List} />

## ListItem

A wrapper for individual list items.

<Props of={ListItem} />

---

Next: [Media →](/components/layout/media)
