# Multi List

> A virtualized Multi List widget to toggle any number of items on and off from large sets of data

Multi List widgets are [Input Fields](https://golemui.com/dx/widgets-reference/input-fields/overview.md) that let the user toggle any number of items on and off in a scrolling list. The value bound at the widget's `path` is an array of the selected item values, in the order they were toggled on. Like the [List](https://golemui.com/dx/widgets-reference/input-fields/list.md), the widget virtualizes its rows, so only the items inside the viewport are rendered regardless of how many you pass in.

Selection lives on the rows themselves: a toggled row shows a check square and carries `aria-selected="true"`, and the list is announced as multiselectable. There are no pills. For a compact field with pills and a filter box, use the [Multi Dropdown](https://golemui.com/dx/widgets-reference/input-fields/multi-dropdown.md); for a single value, use the [List](https://golemui.com/dx/widgets-reference/input-fields/list.md).

The list is a single tab stop. `ArrowUp` and `ArrowDown` move the focused row, `PageUp` and `PageDown` move by one viewport, `Home` and `End` jump to the first and last enabled row, and `Enter`, `Space` or a click toggle the focused row. Disabled rows are skipped.

The simplest way to populate `items` is a flat array of strings or numbers: the displayed label and the stored value are the same. When you need a separate stored value (for example an id behind a human-readable name), pass an array of objects and tell the widget which keys to use via [`labelField`](#using-objects) and [`valueField`](#using-objects).


```ts title="multi-list.ts"

export default [
  gui.inputs.multiList('toppings', {
    items: ['Cheese', 'Bacon', 'Mushrooms', 'Olives', 'Peppers', 'Onions'],
    height: 200,
    itemHeight: 40,
    label: 'Toppings',
  }),
];
```

_Live demo on the docs page. Form definition: [multi-list.ts](https://golemui.com/template/widgets-dx/multi-list/multi-list.ts)._

## Props

Use these `props` to customize your Multi List widget.

| prop           | type   | description                                                                                                                         |
| -------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `items`        | array  | **Required**. Array of strings, numbers, or plain objects. See [Using Objects](#using-objects).                                     |
| `height`       | number | Total height of the scrollable viewport. Defaults to `300`                                                                          |
| `hint`         | string | A description to display below the list                                                                                             |
| `itemHeight`   | number | Fixed height of each item for virtualization logic. Defaults to `40`                                                                |
| `itemRenderer` | string | Key of a registered renderer used to draw each item. See [Item Renderers](https://golemui.com/dx/features/item-renderers.md)                                |
| `labelField`   | string | When items are objects, the key whose value is shown to the user. Defaults to `label`.                                              |
| `valueField`   | string | When items are objects, the key whose value is stored in the form. Defaults to `value`. Required for selection to emit a primitive. |

There is no prop that caps the number of selections. Use the array validator's `maxItems` instead; see [Validation](#validation).

### Using Objects

The top-of-page demo uses an array of strings: each entry is both what the user sees and what gets stored. That is enough when label and value are identical, but lists are often backed by domain data where the human-readable name and the stored identifier differ.

For that case, pass `items` as plain objects and use `labelField` and `valueField` to tell the list which key holds the displayed text and which one holds the stored value. The value array holds the `valueField` primitives, never the objects.


```ts title="multi-list.ts"

export default [
  gui.inputs.multiList('countries', {
    height: 200,
    itemHeight: 40,
    labelField: 'name',
    valueField: 'code',
    items: [
      {
        name: 'USA',
        code: 'US',
      },
      {
        name: 'Canada',
        code: 'CA',
      },
      {
        name: 'Mexico',
        code: 'MX',
      },
      {
        name: 'Brazil',
        code: 'BR',
      },
      {
        name: 'Argentina',
        code: 'AR',
      },
    ],
    label: 'Countries',
  }),
];
```

_Live demo on the docs page. Form definition: [multi-list-custom.ts](https://golemui.com/template/widgets-dx/multi-list/multi-list-custom.ts)._

If your objects already use the default key names (`label` and `value`), you can omit `labelField` and `valueField` entirely. Otherwise both should be set so selection can extract the right primitive.

### Hint

<Aside>A `label` is required for the `hint` to be displayed.</Aside>

Use the property `hint` to provide additional context for the list.


```ts title="multi-list.ts"

export default [
  gui.inputs.multiList('channels', {
    hint: 'Toggle every channel you want alerts on. Enter or Space toggles the focused row.',
    height: 160,
    items: ['Email', 'SMS', 'Push', 'Slack'],
    label: 'Notification channels',
  }),
];
```

_Live demo on the docs page. Form definition: [multi-list-hint.ts](https://golemui.com/template/widgets-dx/multi-list/multi-list-hint.ts)._

### Item Renderer

Use the property `itemRenderer` to draw each row with a registered renderer instead of the default template. The key must match one of the renderers registered on the form host; see [Item Renderers](https://golemui.com/dx/features/item-renderers.md) for the full setup.

The default template is what draws the check square. A custom renderer replaces the whole row, so read `selected` from the render context to mark toggled rows yourself. This demo uses the registered `complexListItemRenderer`, which paints a title and description per row and highlights the selected ones. Bump `itemHeight` to match the renderer's row height so virtualization stays accurate.


```ts title="multi-list.ts"

export default [
  gui.inputs.multiList('templates', {
    height: 240,
    itemHeight: 60,
    labelField: 'title',
    valueField: 'value',
    itemRenderer: 'complexListItemRenderer',
    items: [
      {
        value: 'blog',
        title: 'Blog',
        description: 'A minimalist Markdown blog with RSS feed and dark mode.',
      },
      {
        value: 'docs',
        title: 'Documentation Site',
        description: 'Versioned docs with full-text search and a live playground.',
      },
      {
        value: 'dashboard',
        title: 'Admin Dashboard',
        description: 'Data tables, charts, and role-based auth out of the box.',
      },
      {
        value: 'storefront',
        title: 'E-commerce Storefront',
        description: 'Product catalog, cart, and Stripe checkout wired up.',
      },
      {
        value: 'landing',
        title: 'Marketing Landing',
        description: 'Hero, pricing tiers, and a contact form ready to ship.',
      },
      {
        value: 'portfolio',
        title: 'Developer Portfolio',
        description: 'Showcase projects, embed demos, and host a personal blog.',
      },
    ],
    label: 'Pick your starter templates',
  }),
];
```

_Live demo on the docs page. Form definition: [multi-list-item-renderer.ts](https://golemui.com/template/widgets-dx/multi-list/multi-list-item-renderer.ts)._

### Size

Use `height` to set the scrollable viewport height (default `300`) and `itemHeight` to set each row's height (default `40`). Both are in pixels; the list virtualizes and scrolls when the items exceed the viewport, and `PageUp` and `PageDown` move by `height / itemHeight` rows.


```ts title="multi-list.ts"

export default [
  gui.inputs.multiList('weekdays', {
    hint: 'A 160px viewport with 32px rows',
    height: 160,
    itemHeight: 32,
    items: ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'],
    label: 'Working days',
  }),
];
```

_Live demo on the docs page. Form definition: [multi-list-size.ts](https://golemui.com/template/widgets-dx/multi-list/multi-list-size.ts)._

### Validation

The value is an array, so the widget takes the array validator: `required`, `minItems` and `maxItems`. The widget never refuses a toggle. A selection past `maxItems` is stored and the validator flags it, so the user is told why instead of clicking a row that does nothing. Override the default error copy per rule with a `messages` object; see [Features / Validators](https://golemui.com/dx/features/validators.md#array-validator) for the full rule list.

The demo caps the selection at two. Toggle a third row and tab away to see the error.


```ts title="multi-list.ts"

export default [
  gui.inputs.multiList('frameworks', {
    hint: 'A third selection is stored and flagged, not blocked',
    height: 200,
    items: ['React', 'Angular', 'Vue', 'Lit', 'Svelte', 'Solid'],
    label: 'Frameworks (one or two)',
    validator: {
      required: true,
      minItems: 1,
      maxItems: 2,
      messages: {
        required: 'Pick at least one framework',
        maxItems: 'No more than two frameworks',
      },
    },
  }),
];
```

_Live demo on the docs page. Form definition: [multi-list-validation.ts](https://golemui.com/template/widgets-dx/multi-list/multi-list-validation.ts)._

## Styling

Multi Lists can be styled as explained in the [Styling Guide](https://golemui.com/dx/styling/overview.md). They share the List styles and add the check square.

### CSS Variables

Following you will find a list with the CSS Variables and a quick description of what you will style.

| CSS Variable                 | Description                                               |
| ---------------------------- | --------------------------------------------------------- |
| `--gui-bg-default`           | Background color for the list container                   |
| `--gui-border-default`       | Border color for the list container                       |
| `--gui-radius-md`            | Border radius for the list container and the check square |
| `--gui-intent-primary`       | Background color for selected rows                        |
| `--gui-intent-primary-hover` | Background color for rows on hover                        |
| `--gui-intent-primary-text`  | Text and check mark color for selected and hovered rows   |
| `--gui-shadow-focus`         | Box shadow of the focused row                             |
| `--gui-bg-disabled`          | Background color for disabled rows                        |

### Anatomy

This is the anatomy of the Multi List Widget in case you want to use your CSS styles.


```html title="multi-list-anatomy.html"
<gui-multi-list-input class="gui-multi-list-widget gui-field">
  <gui-label>
    <span class="gui-label" id="fieldUid_label">
      <span class="gui-label__text">Toppings</span>
    </span>
  </gui-label>

  <div class="gui-widget">
    <gui-multi-list
      aria-labelledby="fieldUid_label"
      role="listbox"
      tabindex="0"
      aria-multiselectable="true"
    >
      <div
        role="option"
        tabindex="-1"
        class="gui-list__item-wrapper"
        id="fieldUid-item-0"
        aria-selected="true"
        aria-disabled="false"
        style="height: 40px"
      >
        <div class="gui-list__item gui-list__item-selected">
          <span class="gui-list__item-check" aria-hidden="true">
            <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 256 256">
              <path d="M229.66,77.66l-128,1…"></path>
            </svg>
          </span>
          Cheese
        </div>
      </div>

      <div
        role="option"
        tabindex="-1"
        class="gui-list__item-wrapper"
        id="fieldUid-item-1"
        aria-selected="false"
        aria-disabled="false"
        style="height: 40px"
      >
        <div class="gui-list__item">
          <span class="gui-list__item-check" aria-hidden="true">
            <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 256 256">
              <path d="M229.66,77.66l-128,1…"></path>
            </svg>
          </span>
          Bacon
        </div>
      </div>
      <!-- More option elements (6 in total) -->
    </gui-multi-list>
  </div>
</gui-multi-list-input>
```
