# Multiselect

> Choose several from a long list, such as the characters in a scene, each carrying its board number from the stripboard, with a filter and a way to add a new one.

Source: https://kwark.space/designSystem/components/multiselect

## Usage

### What it is
A multiselect holds several chosen items as tokens in one field, with a filtered list under it. In Kwark the list is usually people of the story, so every character carries their **board number**: the same number in the same small circle that the [Stripboard strip](https://kwark.space/designSystem/components/stripboard-strip.md) and the call sheet print. *1 Mira* in the scene’s field is *1* on the strip.

### When to use
- Many choices from a long, growing list: characters in a scene, departments a call sheet goes to, locations in a block.

### When not to
- Up to about six fixed options, all worth seeing: [Checkboxes](https://kwark.space/designSystem/components/checkbox-and-radio.md).
- One choice: a [Select](https://kwark.space/designSystem/components/select.md) or a [Combobox](https://kwark.space/designSystem/components/combobox.md).
- Filtering a view (not editing data): [Removable tag](https://kwark.space/designSystem/components/removable-tag.md) filters and chips.

### Behaviour
- Typing filters the list; the field never clears what is already chosen.
- Enter or a click toggles the active option and keeps the list open, so several can be chosen in a row. Escape closes it.
- When nothing matches, the last row offers to add what was typed (*Add “Na” as a new character*). Structure is optional in Kwark: a writer is never forced to create a character in the cast list before using one.
- Backspace in an empty input removes the last token (and announces it).
- The footer counts what is chosen and offers *Clear*.

**Do:** Tokens *1 Mira* and *2 Aanya*, the list filtered by *Na*, and *Add “Na” as a new character* at the end.

**Don't:** A scrolling box of 24 checkboxes with no filter, where the chosen ones disappear off the top.

### Writing
- The label names the set and its owner: *Characters in Scene 12*.
- The placeholder is the action: *Add a character*. Empty, with nothing chosen, it states the fact: *Nobody yet*.

## Style

### Anatomy

1. **Field**: at least 36px, wraps to more lines as tokens are added; 1px `--k-line`, 6px corners. Open or focused: `--k-accent-soft` edge.
2. **Token**: 26px pill on `--k-surface` with 1px line; the board number in a 20px circle (`--k-cal-shoot-bg`, 600 11px tabular), the name in 500 12px, and a 22px remove button with a 12px cross (28px on touch).
3. **Input**: grows to fill the line, at least 90px.
4. **List**: a floating panel (`--k-surface`, 1px line, 10px corners, `--k-shadow-pop`), 4px padding. Rows 40px (44 on touch): a 16px tick box, the board number, the name, and *38 scenes* in tabular `--k-text-2`.
5. **Active row**: `--k-raise` with a 2px ink line on its left edge. Chosen: the tick box fills with `--k-accent` and a `--k-on-accent` tick.
6. **Footer**: 1px rule, the count in 12px tabular, *Clear* as an underlined text button.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-bg` | #f8fafc | #191919 |
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-line-strong` | var(--k-text-2) | var(--k-text-2) |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-accent` | #98633f | #98633f |
| `--k-on-accent` | #ffffff | #ffffff |
| `--k-accent-soft` | #e8b58b | #e8b58b |
| `--k-cal-shoot-bg` | #f0ebd6 | #2d2919 |
| `--k-cal-shoot-ink` | #4d4019 | #e5d89e |
| `--k-shadow-pop` | 0 1px 2px rgba(15, 23, 42, .06), 0 12px 32px rgba(15, 23, 42, .12) | 0 2px 6px rgba(0, 0, 0, .2), 0 16px 36px rgba(0, 0, 0, .55) |
| `--k-radius-control` | 6px |  |
| `--k-radius-card` | 10px |  |
| `--k-radius-pill` | 999px |  |

## Code

### React

Use the HTML below with `kwark.css`. The example shows the markup and styling. Supply any application behavior described on this page.

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<div class="kw-specimen-row">
<div class="kw-multi"><span class="kw-label">Characters in Scene 12</span>
  <div class="kw-multi__box is-open"><span class="kw-multi__token"><span class="kw-castno">1</span>Mira<button class="kw-ibtn" type="button" aria-label="Remove Mira from Scene 12"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12"/></svg></button></span><span class="kw-multi__token"><span class="kw-castno">2</span>Aanya<button class="kw-ibtn" type="button" aria-label="Remove Aanya from Scene 12"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12"/></svg></button></span><input type="text" value="Na" role="combobox" aria-expanded="true" aria-autocomplete="list" aria-label="Add a character to Scene 12"><button class="kw-ibtn" type="button" aria-label="Show all characters" aria-expanded="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m18 15-6-6-6 6"/></svg></button></div>
  <div class="kw-pop kw-multi__pop">
    <ul class="kw-multi__list" role="listbox" aria-multiselectable="true" aria-label="Characters">
      <li class="kw-multi__opt is-active" role="option" aria-selected="false"><span class="kw-tick"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M20 6 9 17l-5-5"/></svg></span><span class="kw-castno">3</span><span>Nana</span><small>9 scenes</small></li>
      <li class="kw-multi__opt" role="option" aria-selected="false"><span class="kw-tick"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M20 6 9 17l-5-5"/></svg></span><span class="kw-castno">7</span><span>Dr. Nandini</span><small>2 scenes</small></li>
      <li class="kw-multi__opt kw-multi__opt--add" role="option" aria-selected="false"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 5v14M5 12h14"/></svg><span>Add <b>“Na”</b> as a new character</span></li>
    </ul>
    <div class="kw-multi__foot"><span>2 chosen · 24 characters</span><button class="kw-linkbtn" type="button">Clear</button></div>
  </div>
</div>
<div style="display:grid;gap:20px;align-content:start">
<div class="kw-multi"><span class="kw-label">Characters in Scene 14</span>
  <div class="kw-multi__box"><span class="kw-multi__token"><span class="kw-castno">1</span>Mira<button class="kw-ibtn" type="button" aria-label="Remove Mira from Scene 12"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12"/></svg></button></span><span class="kw-multi__token"><span class="kw-castno">5</span>Courier<button class="kw-ibtn" type="button" aria-label="Remove Courier from Scene 12"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12"/></svg></button></span><span class="kw-multi__token"><span class="kw-castno">6</span>Lab guard<button class="kw-ibtn" type="button" aria-label="Remove Lab guard from Scene 12"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12"/></svg></button></span><input type="text" placeholder="Add a character" role="combobox" aria-expanded="false" aria-autocomplete="list" aria-label="Add a character to Scene 14"><button class="kw-ibtn" type="button" aria-label="Show all characters" aria-expanded="false"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></button></div>
  <span class="kw-hint">The numbers are the board numbers from the stripboard.</span></div>
<div class="kw-multi"><span class="kw-label">Characters in Scene 15</span>
  <div class="kw-multi__box"><input type="text" placeholder="Nobody yet" role="combobox" aria-expanded="false" aria-autocomplete="list" aria-label="Add a character to Scene 15"><button class="kw-ibtn" type="button" aria-label="Show all characters" aria-expanded="false"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></button></div></div>
</div>
</div>
```

## Accessibility

### Keyboard
| Key | Does |
|---|---|
| Typing | Filters; the first match becomes active. |
| Down / Up | Moves the active option (focus stays in the input). |
| Enter | Toggles the active option; the list stays open. |
| Backspace (empty input) | Removes the last token. |
| Escape | Closes the list. |
| Tab | Leaves the field; tokens’ remove buttons are reached with Shift + Tab. |

### Roles and names
- The input is `role="combobox"` with `aria-expanded`, `aria-autocomplete="list"`, `aria-controls` and `aria-activedescendant`.
- The list is `role="listbox"` with `aria-multiselectable="true"`; each row is `role="option"` with `aria-selected`.
- Each token’s remove button names the person and the place: *Remove Mira from Scene 12*. Removing announces *Mira removed* in a polite live region.
- Board numbers are read as part of the row (*3, Nana, 9 scenes*); the tick is drawn and `aria-hidden`.

## For agents

### Rules

- **Must** keep chosen items visible as tokens while the list is filtered.
- **Always** show a character’s board number from the stripboard beside their name, wherever they are chosen.
- **Must** offer to add a typed name that does not match; never require creating it elsewhere first.
- **Must** name every remove button with the item and where it is removed from.
- **Never** close the list after each choice; multiselect is for choosing several in a row.

### AI readiness test

**Task:** Let the writer set which characters appear in Scene 12 from the scene’s detail panel.

**Give the agent:** Multiselect, Stripboard strip, Character card.

**Constraint:** There are 24 characters; the writer may name someone new while choosing.

**A reliable answer:**
- Tokens with board numbers
- Filter by typing
- Enter toggles and keeps the list open
- Add “name” as a new character row
- Remove buttons named with the scene
- listbox with aria-multiselectable
