# List

```ts
import { List } from 'cx/widgets';
```



The `List` widget displays a collection of items and offers navigation and selection. It supports keyboard navigation, single or multiple selection, grouping, and sorting.

```tsx
import { createModel } from "cx/data";
import { Controller, KeySelection } from "cx/ui";
import { List } from "cx/widgets";

interface Item {
  id: number;
  text: string;
  description: string;
}

interface Model {
  records: Item[];
  selection: number;
  $record: Item;
}

const m = createModel<Model>();

class PageController extends Controller {
  onInit() {
    this.store.set(
      m.records,
      Array.from({ length: 5 }, (_, i) => ({
        id: i + 1,
        text: `Item ${i + 1}`,
        description: `Description for item ${i + 1}`,
      })),
    );
  }
}

export default (
  <div controller={PageController}>
    <List
      records={m.records}
      selection={{ type: KeySelection, bind: m.selection, keyField: "id" }}
      mod="bordered"
      style="width: 300px"
      emptyText="No items found."
      recordAlias={m.$record}
    >
      <div class="font-medium" text={m.$record.text} />
      <div class="text-gray-500" text={m.$record.description} />
    </List>
  </div>
);

```

## Configuration

### Core Properties

| Property       | Type      | Default     | Description                                              |
| -------------- | --------- | ----------- | -------------------------------------------------------- |
| `records`      | `array`   |             | Array of records to display                              |
| `recordAlias`  | `string`  | `"$record"` | Alias used to expose record data in templates            |
| `indexAlias`   | `string`  | `"$index"`  | Alias used to expose record index                        |
| `emptyText`    | `string`  |             | Text displayed when the list is empty                    |
| `selection`    | `config`  |             | Selection configuration. See [Selections](/docs/concepts/selections) |

### Sorting

| Property        | Type     | Description                                                |
| --------------- | -------- | ---------------------------------------------------------- |
| `sortField`     | `string` | Binding to store the field name used for sorting           |
| `sortDirection` | `string` | Binding to store sort direction (`"ASC"` or `"DESC"`)      |
| `sorters`       | `array`  | Array of `{ field, direction }` objects for complex sorting |
| `sortOptions`   | `object` | Options for `Intl.Collator` sorting                        |

### Appearance

| Property    | Type            | Description                              |
| ----------- | --------------- | ---------------------------------------- |
| `itemStyle` | `string/object` | CSS style applied to all list items      |
| `itemClass` | `string/object` | CSS class applied to all list items      |
| `grouping`  | `config`        | Grouping configuration for organizing items |

### Behavior

| Property                  | Type      | Default | Description                                           |
| ------------------------- | --------- | ------- | ----------------------------------------------------- |
| `scrollSelectionIntoView` | `boolean` | `false` | Auto-scroll selected item into view                   |
| `itemDisabled`            | `boolean` |         | Disable specific items                                |
| `selectMode`              | `boolean` | `false` | Selection without cursor navigation                   |
| `selectOnTab`             | `boolean` | `false` | Tab key selects item under cursor                     |