@slotted/angular 0.0.0-stage → 0.1.0-beta.0

package/docs/multi-select.examples.md

@@ -0,0 +1,1922 @@
+<!-- index: ./index.md -->
+# multi-select
+
+`data-ui="multi-select"` · Picks several options shown as tags.
+
+## Examples
+
+### Playground
+
+One control with every axis on it, driven by the controls under the canvas. Add a service, take one back out, and watch the row grow by whole rows rather than by pixels.
+
+Excerpt — not a complete module
+
+```html
+<sl-multi-select
+  aria-label="Affected services"
+  placeholder="Add a service"
+  [defaultValue]="['checkout-api']"
+>
+  <sl-multi-select-item value="checkout-api" label="checkout-api" />
+  <sl-multi-select-item value="payments-worker" label="payments-worker" />
+</sl-multi-select>
+```
+
+### The chips, and where they live
+
+Inside the frame, beside the caret, because this control holds a real input. Each chip is a tag: the same pill, the same remove control, the same geometry stated once in tag.css.
+
+Excerpt — not a complete module
+
+```html
+<sl-multi-select aria-label="Affected services" [(value)]="services">
+  <sl-multi-select-item value="checkout-api" label="checkout-api" />
+</sl-multi-select>
+```
+
+### Creating a value the list does not hold
+
+With creatable, the offer stands as an option — ArrowDown reaches it, aria-activedescendant names it and Enter takes it — and its mark is the plus rather than the check, because nothing is in the set yet.
+
+Excerpt — not a complete module
+
+```html
+<sl-multi-select aria-label="Labels" creatable (valueChangeRequest)="onLabels($event)">
+  <sl-multi-select-item value="regression" label="regression" />
+</sl-multi-select>
+```
+
+### A limit that is a validity, not a silence
+
+At the limit the counter takes the accent, the root carries data-complete, every unchosen option answers aria-disabled, and what was refused leaves through valueRefuse instead of vanishing.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import {
+  SlMultiSelect,
+  SlMultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/angular/multi-select';
+
+const CATEGORIES: MultiSelectOption[] = [
+  { value: 'beverages', label: 'Beverages' },
+  { value: 'condiments', label: 'Condiments' },
+  { value: 'confections', label: 'Confections' },
+  { value: 'dairy', label: 'Dairy products' },
+  { value: 'grains', label: 'Grains and cereals' },
+  { value: 'meat', label: 'Meat and poultry' },
+  { value: 'produce', label: 'Produce' },
+  { value: 'seafood', label: 'Seafood' },
+];
+
+@Component({
+  selector: 'app-multi-select-limit',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlMultiSelect, SlMultiSelectItem],
+  template: `
+    <div slField>
+      <label slFieldLabel>Featured categories</label>
+      <sl-multi-select
+        placeholder="Add a category"
+        [max]="3"
+        [items]="categories"
+        [value]="featured"
+      >
+        @for (category of categories; track category.value) {
+          <sl-multi-select-item [value]="category.value" [label]="category.label" />
+        }
+      </sl-multi-select>
+      <span slFieldDescription>The storefront home page shows up to three categories.</span>
+    </div>
+  `,
+})
+export class MultiSelectLimit {
+  protected readonly categories = CATEGORIES;
+  protected readonly featured = ['beverages', 'confections'];
+}
+```
+
+### Duplicates
+
+The comparison is locale-sensitive, so P1 is already held when p1 is typed. The refusal moves focus to the chip that holds it: the reader is shown where their value is instead of being told nothing happened.
+
+Excerpt — not a complete module
+
+```html
+<sl-multi-select aria-label="Labels" creatable locale="pt-BR" />
+
+<sl-multi-select aria-label="Labels" allowDuplicates creatable />
+```
+
+### Reorder, by keyboard first
+
+Alt with an arrow moves the focused chip one place, following the writing direction; Alt+Home and Alt+End take it to either end. The set is unchanged and the request carries keyboard, so a consumer persisting an order listens for exactly that.
+
+Excerpt — not a complete module
+
+```html
+<sl-multi-select aria-label="Rollback order" reorderable (valueChangeRequest)="onOrder($event)" />
+```
+
+### Pasting many values at once
+
+One list of delimiters serves the key and the paste split, so a control cannot accept a comma-separated list from the clipboard and refuse it from the keyboard. Past the limit, the rest is reported rather than dropped.
+
+Excerpt — not a complete module
+
+```html
+<sl-multi-select aria-label="Notify" addOnPaste creatable [delimiters]="[',', ';']" [max]="5" />
+```
+
+### Editing a chip in place
+
+Enter on a focused chip turns its cell into a field, Enter commits and Escape reverts — which is the grid pattern’s own answer for a cell holding editable content. The commit is one transition, not a removal and an addition.
+
+Excerpt — not a complete module
+
+```html
+<sl-multi-select aria-label="Labels" creatable editable [defaultValue]="['payments-worker']" />
+```
+
+### Filtering, and the mark
+
+The default comparison is locale-sensitive and the mark shows the span the collator matched, rather than a naive substring that would disagree with it. chosenOptions decides whether a value already held stays in the list.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlMultiSelect, SlMultiSelectItem } from '@slotted/angular/multi-select';
+
+const CITIES = [
+  { value: 'cdz', label: 'Cádiz, Spain' },
+  { value: 'dus', label: 'Düsseldorf, Germany' },
+  { value: 'krk', label: 'Kraków, Poland' },
+  { value: 'mmx', label: 'Malmö, Sweden' },
+  { value: 'yul', label: 'Montréal, Canada' },
+  { value: 'gru', label: 'São Paulo, Brazil' },
+  { value: 'zrh', label: 'Zürich, Switzerland' },
+  { value: 'aar', label: 'Aarhus, Denmark' },
+];
+
+@Component({
+  selector: 'app-multi-select-filtering',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlMultiSelect, SlMultiSelectItem],
+  template: `
+    <div slField>
+      <label slFieldLabel>Distributor cities</label>
+      <sl-multi-select placeholder="Search cities">
+        @for (city of cities; track city.value) {
+          <sl-multi-select-item [value]="city.value" [label]="city.label" />
+        }
+      </sl-multi-select>
+      <span slFieldDescription>Type “zur” or “malmo”: accents and case are ignored.</span>
+    </div>
+  `,
+})
+export class MultiSelectFiltering {
+  protected readonly cities = CITIES;
+}
+```
+
+### Groups
+
+A set of options under a heading the group points at with aria-labelledby. A group whose every option was filtered away leaves the surface entirely, so a heading never claims a category matched when none did.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import {
+  SlMultiSelect,
+  SlMultiSelectGroup,
+  SlMultiSelectItem,
+  SlMultiSelectSeparator,
+  type MultiSelectOptionGroup,
+} from '@slotted/angular/multi-select';
+
+const REGIONS: MultiSelectOptionGroup[] = [
+  {
+    label: 'West',
+    options: [
+      { value: 'RNO', label: 'Reno, NV' },
+      { value: 'ONT', label: 'Ontario, CA' },
+      { value: 'SEA', label: 'Kent, WA' },
+    ],
+  },
+  {
+    label: 'Central',
+    options: [
+      { value: 'DFW', label: 'Dallas, TX' },
+      { value: 'JOT', label: 'Joliet, IL' },
+      { value: 'CMH', label: 'Columbus, OH' },
+    ],
+  },
+  {
+    label: 'East',
+    options: [
+      { value: 'SAV', label: 'Savannah, GA' },
+      { value: 'ABE', label: 'Allentown, PA' },
+      { value: 'EWR', label: 'Edison, NJ' },
+    ],
+  },
+];
+
+@Component({
+  selector: 'app-multi-select-groups',
+  imports: [
+    SlField,
+    SlFieldLabel,
+    SlMultiSelect,
+    SlMultiSelectGroup,
+    SlMultiSelectItem,
+    SlMultiSelectSeparator,
+  ],
+  template: `
+    <div slField>
+      <label slFieldLabel>Stocking warehouses</label>
+      <sl-multi-select placeholder="Add a warehouse" [items]="regions" [value]="stocked">
+        @for (region of regions; track region.label; let first = $first) {
+          @if (!first) {
+            <sl-multi-select-separator />
+          }
+          <sl-multi-select-group [label]="region.label">
+            @for (warehouse of region.options; track warehouse.value) {
+              <sl-multi-select-item [value]="warehouse.value" [label]="warehouse.label" />
+            }
+          </sl-multi-select-group>
+        }
+      </sl-multi-select>
+    </div>
+  `,
+})
+export class MultiSelectGroups {
+  protected readonly regions = REGIONS;
+  protected readonly stocked = ['RNO', 'SAV'];
+}
+```
+
+### Overflow, and access to the whole set
+
+wrap grows by rows to three and then scrolls, keeping every chip in the DOM. collapse is one line high for a table row: what did not fit becomes a counting chip that opens the popup, whose band holds every value.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import {
+  SlMultiSelect,
+  SlMultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/angular/multi-select';
+import { SlStack } from '@slotted/angular/stack';
+
+const WAREHOUSES: MultiSelectOption[] = [
+  { value: 'RNO', label: 'Reno, NV' },
+  { value: 'ONT', label: 'Ontario, CA' },
+  { value: 'SEA', label: 'Kent, WA' },
+  { value: 'DFW', label: 'Dallas, TX' },
+  { value: 'JOT', label: 'Joliet, IL' },
+  { value: 'CMH', label: 'Columbus, OH' },
+  { value: 'SAV', label: 'Savannah, GA' },
+  { value: 'ABE', label: 'Allentown, PA' },
+  { value: 'EWR', label: 'Edison, NJ' },
+];
+
+const STOCKED = ['RNO', 'ONT', 'SEA', 'DFW', 'JOT', 'CMH', 'SAV'];
+
+@Component({
+  selector: 'app-multi-select-overflow',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlMultiSelect, SlMultiSelectItem, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Stocking warehouses</label>
+        <sl-multi-select overflow="wrap" [items]="warehouses" [value]="stocked">
+          @for (warehouse of warehouses; track warehouse.value) {
+            <sl-multi-select-item [value]="warehouse.value" [label]="warehouse.label" />
+          }
+        </sl-multi-select>
+        <span slFieldDescription>Wrap: every chip stays in view, up to three rows.</span>
+      </div>
+      <div slField>
+        <label slFieldLabel>Stocking warehouses</label>
+        <sl-multi-select overflow="collapse" [items]="warehouses" [value]="stocked">
+          @for (warehouse of warehouses; track warehouse.value) {
+            <sl-multi-select-item [value]="warehouse.value" [label]="warehouse.label" />
+          }
+        </sl-multi-select>
+        <span slFieldDescription>Collapse: one row, and a count of the rest.</span>
+      </div>
+    </div>
+  `,
+})
+export class MultiSelectOverflow {
+  protected readonly warehouses = WAREHOUSES;
+  protected readonly stocked = STOCKED;
+}
+```
+
+### Sizes
+
+The three control steps, from the geometry every control in the library reads. An empty control is exactly the height of a text field beside it on the same form; a chip is what changes that.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import {
+  SlMultiSelect,
+  SlMultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/angular/multi-select';
+import { SlStack } from '@slotted/angular/stack';
+
+const WAREHOUSES: MultiSelectOption[] = [
+  { value: 'RNO', label: 'Reno, NV' },
+  { value: 'CMH', label: 'Columbus, OH' },
+  { value: 'SAV', label: 'Savannah, GA' },
+  { value: 'DFW', label: 'Dallas, TX' },
+];
+
+const SIZES = [
+  { size: 'sm', label: 'Filter by warehouse' },
+  { size: 'md', label: 'Stocking warehouses' },
+  { size: 'lg', label: 'Return warehouses' },
+] as const;
+
+@Component({
+  selector: 'app-multi-select-sizes',
+  imports: [SlField, SlFieldLabel, SlMultiSelect, SlMultiSelectItem, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      @for (entry of sizes; track entry.size) {
+        <div slField [size]="entry.size">
+          <label slFieldLabel>{{ entry.label }}</label>
+          <sl-multi-select [items]="warehouses" [value]="stocked">
+            @for (warehouse of warehouses; track warehouse.value) {
+              <sl-multi-select-item [value]="warehouse.value" [label]="warehouse.label" />
+            }
+          </sl-multi-select>
+        </div>
+      }
+    </div>
+  `,
+})
+export class MultiSelectSizes {
+  protected readonly sizes = SIZES;
+  protected readonly warehouses = WAREHOUSES;
+  protected readonly stocked = ['RNO', 'CMH'];
+}
+```
+
+### Variants
+
+outline for a form, subtle for a panel that already has a ground, and plain for a table cell — where an edge and a resting shadow would draw a cell that is not there.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import {
+  SlMultiSelect,
+  SlMultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/angular/multi-select';
+import { SlStack } from '@slotted/angular/stack';
+
+const CHANNELS: MultiSelectOption[] = [
+  { value: 'web', label: 'Web store' },
+  { value: 'marketplace', label: 'Marketplace' },
+  { value: 'wholesale', label: 'Wholesale' },
+  { value: 'phone', label: 'Phone orders' },
+];
+
+const VARIANTS = [
+  { variant: 'outline', label: 'Sales channels' },
+  { variant: 'subtle', label: 'Promotion channels' },
+  { variant: 'plain', label: 'Report channels' },
+] as const;
+
+@Component({
+  selector: 'app-multi-select-variants',
+  imports: [SlField, SlFieldLabel, SlMultiSelect, SlMultiSelectItem, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      @for (entry of variants; track entry.variant) {
+        <div slField>
+          <label slFieldLabel>{{ entry.label }}</label>
+          <sl-multi-select [variant]="entry.variant" [items]="channels" [value]="chosen">
+            @for (channel of channels; track channel.value) {
+              <sl-multi-select-item [value]="channel.value" [label]="channel.label" />
+            }
+          </sl-multi-select>
+        </div>
+      }
+    </div>
+  `,
+})
+export class MultiSelectVariants {
+  protected readonly variants = VARIANTS;
+  protected readonly channels = CHANNELS;
+  protected readonly chosen = ['web', 'wholesale'];
+}
+```
+
+### States
+
+disabled answers nothing and keeps its values legible; readOnly keeps the caret and the copy and withholds the popup and every remove control; invalid retints the border and the focus ring together.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldError, SlFieldLabel } from '@slotted/angular/field';
+import {
+  SlMultiSelect,
+  SlMultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/angular/multi-select';
+import { SlStack } from '@slotted/angular/stack';
+
+const WAREHOUSES: MultiSelectOption[] = [
+  { value: 'RNO', label: 'Reno, NV' },
+  { value: 'CMH', label: 'Columbus, OH' },
+  { value: 'SAV', label: 'Savannah, GA' },
+  { value: 'DFW', label: 'Dallas, TX' },
+];
+
+@Component({
+  selector: 'app-multi-select-states',
+  imports: [
+    SlField,
+    SlFieldDescription,
+    SlFieldError,
+    SlFieldLabel,
+    SlMultiSelect,
+    SlMultiSelectItem,
+    SlStack,
+  ],
+  template: `
+    <div slStack [gap]="5">
+      <div slField invalid required>
+        <label slFieldLabel>Stocking warehouses</label>
+        <sl-multi-select placeholder="Add a warehouse" [items]="warehouses">
+          @for (warehouse of warehouses; track warehouse.value) {
+            <sl-multi-select-item [value]="warehouse.value" [label]="warehouse.label" />
+          }
+        </sl-multi-select>
+        <span slFieldError>Choose at least one warehouse before publishing.</span>
+      </div>
+      <div slField readOnly>
+        <label slFieldLabel>Warehouses holding stock</label>
+        <sl-multi-select [items]="warehouses" [value]="holding">
+          @for (warehouse of warehouses; track warehouse.value) {
+            <sl-multi-select-item [value]="warehouse.value" [label]="warehouse.label" />
+          }
+        </sl-multi-select>
+        <span slFieldDescription>Updated by the nightly inventory sync.</span>
+      </div>
+      <div slField disabled>
+        <label slFieldLabel>Transfer warehouses</label>
+        <sl-multi-select [items]="warehouses" [value]="transfer">
+          @for (warehouse of warehouses; track warehouse.value) {
+            <sl-multi-select-item [value]="warehouse.value" [label]="warehouse.label" />
+          }
+        </sl-multi-select>
+        <span slFieldDescription>Transfers open once the purchase order is received.</span>
+      </div>
+    </div>
+  `,
+})
+export class MultiSelectStates {
+  protected readonly warehouses = WAREHOUSES;
+  protected readonly holding = ['RNO', 'SAV'];
+  protected readonly transfer = ['CMH'];
+}
+```
+
+### Loading, and nothing found
+
+While an answer travels the control shows the ring where the chevron stood and the popup shows rows the height of an option — the shape of the list that is coming. A query nothing answered keeps the surface’s measure rather than collapsing it.
+
+Excerpt — not a complete module
+
+```html
+<sl-multi-select aria-label="Services" loading />
+
+<sl-multi-select aria-label="Services" [messages]="{ empty: 'No service by that name' }" />
+```
+
+### Content the family did not choose
+
+A forty-character service name truncates inside its chip and stays whole in the accessibility tree; the row wraps rather than pushing the frame wider; and under 120 pixels there is no chip at all and the counter answers instead.
+
+Excerpt — not a complete module
+
+```html
+<sl-multi-select
+  aria-label="Affected services"
+  [defaultValue]="['notification-relay-eu-west-1-canary']"
+/>
+```
+
+### The keyboard
+
+Backspace from an empty field moves to the last chip and removes nothing; a second press removes it. Delete takes the focused chip out, the arrows walk the row, and a printable character sends the reader back to the field.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import {
+  SlMultiSelect,
+  SlMultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/angular/multi-select';
+
+const CARRIERS: MultiSelectOption[] = [
+  { value: 'ups', label: 'UPS Ground' },
+  { value: 'fedex', label: 'FedEx Ground' },
+  { value: 'usps', label: 'USPS Priority Mail' },
+  { value: 'dhl', label: 'DHL Express' },
+  { value: 'ontrac', label: 'OnTrac' },
+];
+
+@Component({
+  selector: 'app-multi-select-keyboard',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlMultiSelect, SlMultiSelectItem],
+  template: `
+    <div slField>
+      <label slFieldLabel>Carrier priority</label>
+      <sl-multi-select
+        reorderable
+        placeholder="Add a carrier"
+        [items]="carriers"
+        [value]="priority"
+      >
+        @for (carrier of carriers; track carrier.value) {
+          <sl-multi-select-item [value]="carrier.value" [label]="carrier.label" />
+        }
+      </sl-multi-select>
+      <span slFieldDescription>
+        Rates are requested from the first carrier, then the next. Alt with an arrow moves the
+        focused carrier.
+      </span>
+    </div>
+  `,
+})
+export class MultiSelectKeyboard {
+  protected readonly carriers = CARRIERS;
+  protected readonly priority = ['usps', 'ups', 'fedex'];
+}
+```
+
+### In a form
+
+One hidden input per value, all under the same name, and a ControlValueAccessor with a Validator beside it — so a Reactive Form sees required, tooMany and duplicate without the consumer writing one.
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { FormControl, FormGroup, ReactiveFormsModule } from '@angular/forms';
+import { SlButton } from '@slotted/angular/button';
+import { SlField, SlFieldError, SlFieldLabel } from '@slotted/angular/field';
+import { SlInline } from '@slotted/angular/inline';
+import {
+  SlMultiSelect,
+  SlMultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/angular/multi-select';
+import { SlStack } from '@slotted/angular/stack';
+import { SlText } from '@slotted/angular/typography';
+
+const WAREHOUSES: MultiSelectOption[] = [
+  { value: 'RNO', label: 'Reno, NV' },
+  { value: 'CMH', label: 'Columbus, OH' },
+  { value: 'SAV', label: 'Savannah, GA' },
+  { value: 'DFW', label: 'Dallas, TX' },
+];
+
+const CHANNELS: MultiSelectOption[] = [
+  { value: 'web', label: 'Web store' },
+  { value: 'marketplace', label: 'Marketplace' },
+  { value: 'wholesale', label: 'Wholesale' },
+];
+
+@Component({
+  selector: 'app-multi-select-form',
+  imports: [
+    ReactiveFormsModule,
+    SlButton,
+    SlField,
+    SlFieldError,
+    SlFieldLabel,
+    SlInline,
+    SlMultiSelect,
+    SlMultiSelectItem,
+    SlStack,
+    SlText,
+  ],
+  template: `
+    <form novalidate [formGroup]="form" (ngSubmit)="submit()" (reset)="clear()">
+      <div slStack [gap]="5">
+        <div slField required [invalid]="missing() ? true : undefined">
+          <label slFieldLabel>Stocking warehouses</label>
+          <sl-multi-select
+            name="warehouses"
+            placeholder="Add a warehouse"
+            formControlName="warehouses"
+            [items]="warehouses"
+            (valueChange)="missing.set(false)"
+          >
+            @for (warehouse of warehouses; track warehouse.value) {
+              <sl-multi-select-item [value]="warehouse.value" [label]="warehouse.label" />
+            }
+          </sl-multi-select>
+          <span slFieldError live="polite" reserve>{{
+            missing() ? 'Choose at least one warehouse to stock this product.' : ''
+          }}</span>
+        </div>
+        <div slField>
+          <label slFieldLabel>Sales channels</label>
+          <sl-multi-select name="channels" formControlName="channels" [items]="channels">
+            @for (channel of channels; track channel.value) {
+              <sl-multi-select-item [value]="channel.value" [label]="channel.label" />
+            }
+          </sl-multi-select>
+        </div>
+        <div slInline [gap]="3" align="center">
+          <button slButton type="submit">Save</button>
+          <button slButton type="reset" tone="secondary" variant="outline">Reset</button>
+          @if (saved(); as message) {
+            <span slText size="sm" tone="muted">{{ message }}</span>
+          }
+        </div>
+      </div>
+    </form>
+  `,
+})
+export class MultiSelectForm {
+  protected readonly warehouses = WAREHOUSES;
+  protected readonly channels = CHANNELS;
+  /* The control's own Validator reports required, so none is written here. */
+  protected readonly form = new FormGroup({
+    warehouses: new FormControl<readonly string[]>([], { nonNullable: true }),
+    channels: new FormControl<readonly string[]>(['web'], { nonNullable: true }),
+  });
+  protected readonly missing = signal(false);
+  protected readonly saved = signal<string | null>(null);
+
+  protected submit(): void {
+    this.missing.set(this.form.controls.warehouses.invalid);
+    const { warehouses } = this.form.getRawValue();
+    this.saved.set(
+      this.form.valid
+        ? `Saved with ${warehouses.length} of ${WAREHOUSES.length} warehouses.`
+        : null,
+    );
+  }
+
+  protected clear(): void {
+    this.missing.set(false);
+    this.saved.set(null);
+  }
+}
+```
+
+### Composition, and the defaults an application sets once
+
+An injection token carries the axes, provideSlotted the language, exportAs reaches the instance from the template, and projected options keep their own content.
+
+Excerpt — not a complete module
+
+```html
+<sl-multi-select #services="slMultiSelect" aria-label="Affected services" />
+
+<button type="button" (click)="services.focus()">Add a service</button>
+```
+
+### async-search.ts
+
+Example
+
+```ts
+import { Component, effect, signal } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlMultiSelect, SlMultiSelectItem } from '@slotted/angular/multi-select';
+
+interface Customer {
+  value: string;
+  label: string;
+  city: string;
+}
+
+const CUSTOMERS: Customer[] = [
+  { value: 'ALFKI', label: 'Alfreds Futterkiste', city: 'Berlin' },
+  { value: 'ANATR', label: 'Ana Trujillo Emparedados', city: 'México D.F.' },
+  { value: 'BERGS', label: 'Berglunds snabbköp', city: 'Luleå' },
+  { value: 'BLAUS', label: 'Blauer See Delikatessen', city: 'Mannheim' },
+  { value: 'BONAP', label: 'Bon app’', city: 'Marseille' },
+  { value: 'BOTTM', label: 'Bottom-Dollar Markets', city: 'Tsawassen' },
+  { value: 'ERNSH', label: 'Ernst Handel', city: 'Graz' },
+  { value: 'FOLKO', label: 'Folk och fä HB', city: 'Bräcke' },
+  { value: 'FRANK', label: 'Frankenversand', city: 'München' },
+  { value: 'QUICK', label: 'QUICK-Stop', city: 'Cunewalde' },
+  { value: 'RATTC', label: 'Rattlesnake Canyon Grocery', city: 'Albuquerque' },
+  { value: 'SAVEA', label: 'Save-a-lot Markets', city: 'Boise' },
+];
+
+/** Stands in for the customer search endpoint, which filters on the server. */
+const searchCustomers = (query: string) =>
+  new Promise<Customer[]>((resolve) =>
+    setTimeout(() => {
+      const needle = query.trim().toLowerCase();
+      resolve(CUSTOMERS.filter((customer) => customer.label.toLowerCase().includes(needle)));
+    }, 600),
+  );
+
+/** The first page of customers, which arrives with the page itself. */
+const FIRST_PAGE = CUSTOMERS.slice(0, 6);
+
+@Component({
+  selector: 'app-multi-select-async-search',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlMultiSelect, SlMultiSelectItem],
+  template: `
+    <div slField>
+      <label slFieldLabel>Customers in this campaign</label>
+      <sl-multi-select
+        placeholder="Search customers"
+        [filter]="null"
+        [loading]="loading()"
+        [messages]="{ empty: 'No customer by that name.', loading: 'Searching customers…' }"
+        (inputValueChange)="query.set($event)"
+      >
+        @for (customer of results(); track customer.value) {
+          <sl-multi-select-item
+            [value]="customer.value"
+            [label]="customer.label"
+            [description]="customer.city"
+          />
+        }
+      </sl-multi-select>
+      <span slFieldDescription>Each keystroke searches the customer list on the server.</span>
+    </div>
+  `,
+})
+export class MultiSelectAsyncSearch {
+  protected readonly query = signal('');
+  protected readonly results = signal<Customer[]>(FIRST_PAGE);
+  protected readonly loading = signal(false);
+
+  constructor() {
+    effect((onCleanup) => {
+      const query = this.query();
+      if (query.trim() === '') {
+        this.results.set(FIRST_PAGE);
+        this.loading.set(false);
+        return;
+      }
+      let current = true;
+      this.loading.set(true);
+      void searchCustomers(query).then((found) => {
+        if (!current) return;
+        this.results.set(found);
+        this.loading.set(false);
+      });
+      onCleanup(() => {
+        current = false;
+      });
+    });
+  }
+}
+```
+
+### choose-columns.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlInline } from '@slotted/angular/inline';
+import {
+  SlMultiSelect,
+  SlMultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/angular/multi-select';
+import { SlStack } from '@slotted/angular/stack';
+import {
+  SlTable,
+  SlTableBody,
+  SlTableCell,
+  SlTableColumnHeader,
+  SlTableContent,
+  SlTableHead,
+  SlTableRow,
+} from '@slotted/angular/table';
+
+type Column = 'order' | 'customer' | 'placed' | 'items' | 'total';
+
+const COLUMNS: (MultiSelectOption & { value: Column })[] = [
+  { value: 'order', label: 'Order' },
+  { value: 'customer', label: 'Customer' },
+  { value: 'placed', label: 'Placed' },
+  { value: 'items', label: 'Items' },
+  { value: 'total', label: 'Total' },
+];
+
+const ORDERS: Record<Column, string>[] = [
+  {
+    order: 'SO-10482',
+    customer: 'Harbor & Pine',
+    placed: 'Oct 2',
+    items: '14',
+    total: '$1,240.00',
+  },
+  {
+    order: 'SO-10483',
+    customer: 'Brightline Studio',
+    placed: 'Oct 3',
+    items: '3',
+    total: '$318.50',
+  },
+  {
+    order: 'SO-10484',
+    customer: 'Northgate Labs',
+    placed: 'Oct 3',
+    items: '41',
+    total: '$2,906.10',
+  },
+];
+
+const ALL = COLUMNS.map((column) => column.value);
+const labelOf = (value: string) => COLUMNS.find((column) => column.value === value)?.label;
+
+@Component({
+  selector: 'app-multi-select-choose-columns',
+  imports: [
+    SlButton,
+    SlField,
+    SlFieldDescription,
+    SlFieldLabel,
+    SlInline,
+    SlMultiSelect,
+    SlMultiSelectItem,
+    SlStack,
+    SlTable,
+    SlTableBody,
+    SlTableCell,
+    SlTableColumnHeader,
+    SlTableContent,
+    SlTableHead,
+    SlTableRow,
+  ],
+  template: `
+    <div slStack [gap]="4">
+      <div slField>
+        <div slInline [gap]="3" justify="between" align="center">
+          <label slFieldLabel>Columns</label>
+          <button
+            slButton
+            size="sm"
+            tone="secondary"
+            variant="ghost"
+            [disabled]="shown().length === all.length"
+            (click)="shown.set(all)"
+          >
+            Show all
+          </button>
+        </div>
+        <sl-multi-select reorderable placeholder="Add a column" [items]="options" [(value)]="shown">
+          @for (column of options; track column.value) {
+            <sl-multi-select-item [value]="column.value" [label]="column.label" />
+          }
+        </sl-multi-select>
+        <span slFieldDescription>
+          The table follows the order of the chips. Alt with an arrow moves a focused column.
+        </span>
+      </div>
+      <div slTable [columns]="columnCount()">
+        <div slTableContent aria-label="Orders">
+          <thead slTableHead>
+            <tr slTableRow>
+              @for (column of columns(); track column) {
+                <th slTableColumnHeader>{{ labelOf(column) }}</th>
+              }
+            </tr>
+          </thead>
+          <tbody slTableBody>
+            @for (order of orders; track order.order) {
+              <tr slTableRow [value]="order.order">
+                @for (column of columns(); track column) {
+                  <td slTableCell>{{ order[column] }}</td>
+                }
+              </tr>
+            }
+          </tbody>
+        </div>
+      </div>
+    </div>
+  `,
+})
+export class MultiSelectChooseColumns {
+  protected readonly options = COLUMNS;
+  protected readonly orders = ORDERS;
+  protected readonly all = ALL;
+  protected readonly labelOf = labelOf;
+  protected readonly shown = signal<readonly string[]>(['order', 'customer', 'total']);
+  protected readonly columns = computed(() => this.shown() as readonly Column[]);
+  protected readonly columnCount = computed(() => Math.max(this.columns().length, 1));
+}
+```
+
+### clearing.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import {
+  SlMultiSelect,
+  SlMultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/angular/multi-select';
+import { SlStack } from '@slotted/angular/stack';
+
+const CHANNELS: MultiSelectOption[] = [
+  { value: 'web', label: 'Web store' },
+  { value: 'marketplace', label: 'Marketplace' },
+  { value: 'wholesale', label: 'Wholesale' },
+  { value: 'phone', label: 'Phone orders' },
+];
+
+@Component({
+  selector: 'app-multi-select-clearing',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlMultiSelect, SlMultiSelectItem, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Show orders from</label>
+        <sl-multi-select placeholder="All channels" [items]="channels" [value]="shown">
+          @for (channel of channels; track channel.value) {
+            <sl-multi-select-item [value]="channel.value" [label]="channel.label" />
+          }
+        </sl-multi-select>
+        <span slFieldDescription>The clear button empties the filter in one press.</span>
+      </div>
+      <div slField>
+        <label slFieldLabel>Sell through</label>
+        <sl-multi-select [clearable]="false" [items]="channels" [value]="selling">
+          @for (channel of channels; track channel.value) {
+            <sl-multi-select-item [value]="channel.value" [label]="channel.label" />
+          }
+        </sl-multi-select>
+        <span slFieldDescription>No clear button: channels come off one at a time.</span>
+      </div>
+    </div>
+  `,
+})
+export class MultiSelectClearing {
+  protected readonly channels = CHANNELS;
+  protected readonly shown = ['web', 'marketplace', 'phone'];
+  protected readonly selling = ['web', 'wholesale'];
+}
+```
+
+### controlled.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import {
+  SlMultiSelect,
+  SlMultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/angular/multi-select';
+import { SlStack } from '@slotted/angular/stack';
+import { SlText } from '@slotted/angular/typography';
+
+const WAREHOUSES: MultiSelectOption[] = [
+  { value: 'RNO', label: 'Reno, NV' },
+  { value: 'CMH', label: 'Columbus, OH' },
+  { value: 'SAV', label: 'Savannah, GA' },
+  { value: 'DFW', label: 'Dallas, TX' },
+];
+
+const labelOf = (value: string) => WAREHOUSES.find((option) => option.value === value)?.label;
+
+@Component({
+  selector: 'app-multi-select-controlled',
+  imports: [SlField, SlFieldLabel, SlMultiSelect, SlMultiSelectItem, SlStack, SlText],
+  template: `
+    <div slStack [gap]="3">
+      <div slField>
+        <label slFieldLabel>Stocking warehouses</label>
+        <sl-multi-select
+          placeholder="Add a warehouse"
+          [items]="options"
+          [(value)]="warehouses"
+          (valueChangeRequest)="reason.set($event.reason)"
+        >
+          @for (warehouse of options; track warehouse.value) {
+            <sl-multi-select-item [value]="warehouse.value" [label]="warehouse.label" />
+          }
+        </sl-multi-select>
+      </div>
+      <span slText size="sm" tone="muted">{{ summary() }}</span>
+    </div>
+  `,
+})
+export class MultiSelectControlled {
+  protected readonly options = WAREHOUSES;
+  protected readonly warehouses = signal<readonly string[]>(['RNO', 'CMH']);
+  protected readonly reason = signal<string | null>(null);
+  protected readonly summary = computed(() => {
+    const held = this.warehouses();
+    const stocked =
+      held.length === 0 ? 'Not stocked anywhere' : `Stocked at ${held.map(labelOf).join('; ')}`;
+    const reason = this.reason();
+    return reason === null ? stocked : `${stocked} · last change: ${reason}`;
+  });
+}
+```
+
+### creatable.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import {
+  SlMultiSelect,
+  SlMultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/angular/multi-select';
+
+const SUGGESTED: MultiSelectOption[] = [
+  { value: 'chai', label: 'chai' },
+  { value: 'black tea', label: 'black tea' },
+  { value: 'spiced', label: 'spiced' },
+  { value: 'loose leaf', label: 'loose leaf' },
+  { value: 'caffeinated', label: 'caffeinated' },
+  { value: 'gift', label: 'gift' },
+];
+
+@Component({
+  selector: 'app-multi-select-creatable',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlMultiSelect, SlMultiSelectItem],
+  template: `
+    <div slField>
+      <label slFieldLabel>Search keywords</label>
+      <sl-multi-select creatable placeholder="Add a keyword" [items]="suggested" [value]="keywords">
+        @for (keyword of suggested; track keyword.value) {
+          <sl-multi-select-item [value]="keyword.value" [label]="keyword.label" />
+        }
+      </sl-multi-select>
+      <span slFieldDescription>
+        Type a keyword and press Enter or a comma. Shoppers find Chai tea, 24 bags by these words.
+      </span>
+    </div>
+  `,
+})
+export class MultiSelectCreatable {
+  protected readonly suggested = SUGGESTED;
+  protected readonly keywords = ['chai', 'black tea'];
+}
+```
+
+### defaults.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import {
+  provideMultiSelectDefaults,
+  SlMultiSelect,
+  SlMultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/angular/multi-select';
+import { SlStack } from '@slotted/angular/stack';
+
+const OWNERS: MultiSelectOption[] = [
+  { value: 'avery', label: 'Avery Collins' },
+  { value: 'kenji', label: 'Kenji Watanabe' },
+  { value: 'lucia', label: 'Lucía Fernández' },
+  { value: 'omar', label: 'Omar Haddad' },
+];
+
+const SEGMENTS: MultiSelectOption[] = [
+  { value: 'enterprise', label: 'Enterprise' },
+  { value: 'wholesale', label: 'Wholesale' },
+  { value: 'retail', label: 'Retail' },
+];
+
+@Component({
+  selector: 'app-multi-select-defaults',
+  imports: [SlField, SlFieldLabel, SlMultiSelect, SlMultiSelectItem, SlStack],
+  providers: [provideMultiSelectDefaults({ size: 'sm', variant: 'subtle', overflow: 'collapse' })],
+  template: `
+    <div slStack [gap]="4">
+      <div slField>
+        <label slFieldLabel>Account owners</label>
+        <sl-multi-select placeholder="Any owner" [items]="owners" [value]="ownersChosen">
+          @for (owner of owners; track owner.value) {
+            <sl-multi-select-item [value]="owner.value" [label]="owner.label" />
+          }
+        </sl-multi-select>
+      </div>
+      <div slField>
+        <label slFieldLabel>Segments</label>
+        <sl-multi-select placeholder="Any segment" [items]="segments" [value]="segmentsChosen">
+          @for (segment of segments; track segment.value) {
+            <sl-multi-select-item [value]="segment.value" [label]="segment.label" />
+          }
+        </sl-multi-select>
+      </div>
+    </div>
+  `,
+})
+export class MultiSelectDefaults {
+  protected readonly owners = OWNERS;
+  protected readonly segments = SEGMENTS;
+  protected readonly ownersChosen = ['lucia', 'kenji'];
+  protected readonly segmentsChosen = ['wholesale'];
+}
+```
+
+### descriptions.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import type { GlyphName } from '@slotted/angular/icon';
+import {
+  SlMultiSelect,
+  SlMultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/angular/multi-select';
+
+const DOCUMENTS: (MultiSelectOption & { icon: GlyphName; description: string })[] = [
+  {
+    value: 'invoice',
+    label: 'Invoice',
+    icon: 'file-text',
+    description: 'PDF, issued when the order ships',
+  },
+  {
+    value: 'packing-slip',
+    label: 'Packing slip',
+    icon: 'file',
+    description: 'PDF, one page per parcel',
+  },
+  {
+    value: 'customs',
+    label: 'Customs declaration',
+    icon: 'file-spreadsheet',
+    description: 'CN23, international orders only',
+  },
+  {
+    value: 'photos',
+    label: 'Product photos',
+    icon: 'file-image',
+    description: 'Up to five images per line item',
+  },
+];
+
+@Component({
+  selector: 'app-multi-select-descriptions',
+  imports: [SlField, SlFieldLabel, SlMultiSelect, SlMultiSelectItem],
+  template: `
+    <div slField>
+      <label slFieldLabel>Attach to the shipping email</label>
+      <sl-multi-select placeholder="Add a document" [items]="documents" [value]="attached">
+        @for (document of documents; track document.value) {
+          <sl-multi-select-item
+            [value]="document.value"
+            [label]="document.label"
+            [description]="document.description"
+            [icon]="document.icon"
+          />
+        }
+      </sl-multi-select>
+    </div>
+  `,
+})
+export class MultiSelectDescriptions {
+  protected readonly documents = DOCUMENTS;
+  protected readonly attached = ['invoice'];
+}
+```
+
+### disabled-options.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import {
+  SlMultiSelect,
+  SlMultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/angular/multi-select';
+
+const WAREHOUSES: (MultiSelectOption & { description: string })[] = [
+  { value: 'RNO', label: 'Reno, NV', description: '142 pallet spaces free' },
+  { value: 'CMH', label: 'Columbus, OH', description: '38 pallet spaces free' },
+  {
+    value: 'SAV',
+    label: 'Savannah, GA',
+    description: 'At capacity until November 3',
+    disabled: true,
+  },
+  { value: 'DFW', label: 'Dallas, TX', description: '210 pallet spaces free' },
+  {
+    value: 'ONT',
+    label: 'Ontario, CA',
+    description: 'Closed for a stock count this week',
+    disabled: true,
+  },
+];
+
+@Component({
+  selector: 'app-multi-select-disabled-options',
+  imports: [SlField, SlFieldLabel, SlMultiSelect, SlMultiSelectItem],
+  template: `
+    <div slField>
+      <label slFieldLabel>Receiving warehouses</label>
+      <sl-multi-select placeholder="Add a warehouse" [items]="warehouses" [value]="receiving">
+        @for (warehouse of warehouses; track warehouse.value) {
+          <sl-multi-select-item
+            [value]="warehouse.value"
+            [label]="warehouse.label"
+            [description]="warehouse.description"
+            [disabled]="warehouse.disabled ?? false"
+          />
+        }
+      </sl-multi-select>
+    </div>
+  `,
+})
+export class MultiSelectDisabledOptions {
+  protected readonly warehouses = WAREHOUSES;
+  protected readonly receiving = ['RNO'];
+}
+```
+
+### editable.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlMultiSelect } from '@slotted/angular/multi-select';
+
+@Component({
+  selector: 'app-multi-select-editable',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlMultiSelect],
+  template: `
+    <div slField>
+      <label slFieldLabel>Bin locations</label>
+      <sl-multi-select
+        creatable
+        editable
+        placeholder="Add a bin"
+        [value]="bins"
+        [messages]="{ empty: 'Type a bin code and press Enter.' }"
+      />
+      <span slFieldDescription>
+        Press ArrowLeft to reach a bin, then Enter to correct it in place.
+      </span>
+    </div>
+  `,
+})
+export class MultiSelectEditable {
+  protected readonly bins = ['A-12-03', 'A-12-04', 'C-02-11'];
+}
+```
+
+### email-list.ts
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldError, SlFieldLabel } from '@slotted/angular/field';
+import {
+  SlMultiSelect,
+  SlMultiSelectItem,
+  type MultiSelectRefuseCause,
+} from '@slotted/angular/multi-select';
+
+const TEAMS = [
+  { value: 'purchasing@northwind.example', description: 'Purchasing team' },
+  { value: 'warehouse-ops@northwind.example', description: 'Warehouse operations' },
+  { value: 'category-managers@northwind.example', description: 'Category managers' },
+];
+
+const isEmail = (text: string) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(text.trim());
+
+const REASONS: Record<MultiSelectRefuseCause, string> = {
+  invalid: 'is not an email address',
+  duplicate: 'is already on the list',
+  limit: 'is over the limit',
+};
+
+@Component({
+  selector: 'app-multi-select-email-list',
+  imports: [
+    SlField,
+    SlFieldDescription,
+    SlFieldError,
+    SlFieldLabel,
+    SlMultiSelect,
+    SlMultiSelectItem,
+  ],
+  template: `
+    <div slField [invalid]="refused() !== null ? true : undefined">
+      <label slFieldLabel>Stockout alerts</label>
+      <sl-multi-select
+        creatable
+        placeholder="name@company.com"
+        [delimiters]="delimiters"
+        [value]="recipients"
+        [validateValue]="isEmail"
+        (valueRefuse)="refuse($event)"
+        (valueChange)="refused.set(null)"
+      >
+        @for (team of teams; track team.value) {
+          <sl-multi-select-item
+            [value]="team.value"
+            [label]="team.value"
+            [description]="team.description"
+          />
+        }
+      </sl-multi-select>
+      @if (refused(); as message) {
+        <span slFieldError live="polite">{{ message }}</span>
+      } @else {
+        <span slFieldDescription>Paste a list separated by commas, semicolons or spaces.</span>
+      }
+    </div>
+  `,
+})
+export class MultiSelectEmailList {
+  protected readonly teams = TEAMS;
+  protected readonly delimiters = [',', ';', ' '];
+  protected readonly recipients = ['purchasing@northwind.example'];
+  protected readonly isEmail = isEmail;
+  protected readonly refused = signal<string | null>(null);
+
+  protected refuse(event: { values: readonly string[]; cause: MultiSelectRefuseCause }): void {
+    this.refused.set(`${event.values.join(', ')} ${REASONS[event.cause]}.`);
+  }
+}
+```
+
+### filter-bar.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { SlGrid } from '@slotted/angular/grid';
+import {
+  SlMultiSelect,
+  SlMultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/angular/multi-select';
+import { SlStack } from '@slotted/angular/stack';
+import {
+  SlTable,
+  SlTableBody,
+  SlTableCell,
+  SlTableColumnHeader,
+  SlTableContent,
+  SlTableHead,
+  SlTableRow,
+  SlTableRowHeader,
+} from '@slotted/angular/table';
+import { SlText } from '@slotted/angular/typography';
+
+const ORDERS = [
+  { id: 'SO-10482', customer: 'Harbor & Pine', status: 'open', channel: 'web', total: '$1,240.00' },
+  {
+    id: 'SO-10483',
+    customer: 'Brightline Studio',
+    status: 'on-hold',
+    channel: 'phone',
+    total: '$318.50',
+  },
+  {
+    id: 'SO-10484',
+    customer: 'Northgate Labs',
+    status: 'shipped',
+    channel: 'wholesale',
+    total: '$2,906.10',
+  },
+  { id: 'SO-10485', customer: 'Verde Kitchen', status: 'delayed', channel: 'web', total: '$86.00' },
+  {
+    id: 'SO-10486',
+    customer: 'Quill & Co.',
+    status: 'shipped',
+    channel: 'marketplace',
+    total: '$540.25',
+  },
+  {
+    id: 'SO-10487',
+    customer: 'Atlas Freight',
+    status: 'open',
+    channel: 'wholesale',
+    total: '$1,912.00',
+  },
+  { id: 'SO-10488', customer: 'Lumen Dental', status: 'open', channel: 'web', total: '$472.80' },
+  {
+    id: 'SO-10489',
+    customer: 'Cobalt Outfitters',
+    status: 'delayed',
+    channel: 'marketplace',
+    total: '$1,055.40',
+  },
+];
+
+const STATUSES: MultiSelectOption[] = [
+  { value: 'open', label: 'Open' },
+  { value: 'on-hold', label: 'On hold' },
+  { value: 'delayed', label: 'Delayed' },
+  { value: 'shipped', label: 'Shipped' },
+];
+
+const CHANNELS: MultiSelectOption[] = [
+  { value: 'web', label: 'Web store' },
+  { value: 'marketplace', label: 'Marketplace' },
+  { value: 'wholesale', label: 'Wholesale' },
+  { value: 'phone', label: 'Phone orders' },
+];
+
+type Facet = 'status' | 'channel';
+
+const labelOf = (options: MultiSelectOption[], value: string) =>
+  options.find((option) => option.value === value)?.label;
+
+const countOf = (facet: Facet, value: string) => {
+  const count = ORDERS.filter((order) => order[facet] === value).length;
+  return count === 1 ? '1 order' : `${count} orders`;
+};
+
+@Component({
+  selector: 'app-multi-select-filter-bar',
+  imports: [
+    SlGrid,
+    SlMultiSelect,
+    SlMultiSelectItem,
+    SlStack,
+    SlTable,
+    SlTableBody,
+    SlTableCell,
+    SlTableColumnHeader,
+    SlTableContent,
+    SlTableHead,
+    SlTableRow,
+    SlTableRowHeader,
+    SlText,
+  ],
+  template: `
+    <div slStack [gap]="3">
+      <div slGrid [columns]="2" [gap]="3">
+        <sl-multi-select
+          aria-label="Status"
+          placeholder="All statuses"
+          size="sm"
+          overflow="collapse"
+          [items]="statusOptions"
+          [(value)]="statuses"
+        >
+          @for (status of statusOptions; track status.value) {
+            <sl-multi-select-item
+              [value]="status.value"
+              [label]="status.label"
+              [description]="countOf('status', status.value)"
+            />
+          }
+        </sl-multi-select>
+        <sl-multi-select
+          aria-label="Channel"
+          placeholder="All channels"
+          size="sm"
+          overflow="collapse"
+          [items]="channelOptions"
+          [(value)]="channels"
+        >
+          @for (channel of channelOptions; track channel.value) {
+            <sl-multi-select-item
+              [value]="channel.value"
+              [label]="channel.label"
+              [description]="countOf('channel', channel.value)"
+            />
+          }
+        </sl-multi-select>
+      </div>
+      <span slText size="sm" tone="muted">{{ rows().length }} of {{ orders.length }} orders</span>
+      <div slTable [columns]="5">
+        <div slTableContent aria-label="Orders">
+          <thead slTableHead>
+            <tr slTableRow>
+              <th slTableColumnHeader>Order</th>
+              <th slTableColumnHeader>Customer</th>
+              <th slTableColumnHeader>Status</th>
+              <th slTableColumnHeader>Channel</th>
+              <th slTableColumnHeader numeric>Total</th>
+            </tr>
+          </thead>
+          <tbody slTableBody>
+            @for (order of rows(); track order.id) {
+              <tr slTableRow [value]="order.id">
+                <th slTableRowHeader>{{ order.id }}</th>
+                <td slTableCell>{{ order.customer }}</td>
+                <td slTableCell>{{ labelOf(statusOptions, order.status) }}</td>
+                <td slTableCell>{{ labelOf(channelOptions, order.channel) }}</td>
+                <td slTableCell numeric>{{ order.total }}</td>
+              </tr>
+            }
+          </tbody>
+        </div>
+      </div>
+    </div>
+  `,
+})
+export class MultiSelectFilterBar {
+  protected readonly orders = ORDERS;
+  protected readonly statusOptions = STATUSES;
+  protected readonly channelOptions = CHANNELS;
+  protected readonly labelOf = labelOf;
+  protected readonly countOf = countOf;
+  protected readonly statuses = signal<readonly string[]>(['open', 'delayed']);
+  protected readonly channels = signal<readonly string[]>([]);
+  protected readonly rows = computed(() => {
+    const statuses = this.statuses();
+    const channels = this.channels();
+    return ORDERS.filter(
+      (order) =>
+        (statuses.length === 0 || statuses.includes(order.status)) &&
+        (channels.length === 0 || channels.includes(order.channel)),
+    );
+  });
+}
+```
+
+### initial-value.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import {
+  SlMultiSelect,
+  SlMultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/angular/multi-select';
+
+const WAREHOUSES: MultiSelectOption[] = [
+  { value: 'RNO', label: 'Reno, NV' },
+  { value: 'CMH', label: 'Columbus, OH' },
+  { value: 'SAV', label: 'Savannah, GA' },
+  { value: 'DFW', label: 'Dallas, TX' },
+  { value: 'ONT', label: 'Ontario, CA' },
+  { value: 'ABE', label: 'Allentown, PA' },
+];
+
+@Component({
+  selector: 'app-multi-select-initial-value',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlMultiSelect, SlMultiSelectItem],
+  template: `
+    <div slField>
+      <label slFieldLabel>Stocking warehouses</label>
+      <sl-multi-select placeholder="Add a warehouse" [items]="warehouses" [value]="stocked">
+        @for (warehouse of warehouses; track warehouse.value) {
+          <sl-multi-select-item [value]="warehouse.value" [label]="warehouse.label" />
+        }
+      </sl-multi-select>
+      <span slFieldDescription>Earl Grey, 100 bags is stocked at two warehouses.</span>
+    </div>
+  `,
+})
+export class MultiSelectInitialValue {
+  protected readonly warehouses = WAREHOUSES;
+  protected readonly stocked = ['RNO', 'CMH'];
+}
+```
+
+### loading.ts
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import {
+  SlMultiSelect,
+  SlMultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/angular/multi-select';
+
+const CARRIERS: MultiSelectOption[] = [
+  { value: 'ups', label: 'UPS Ground' },
+  { value: 'fedex', label: 'FedEx Ground' },
+  { value: 'usps', label: 'USPS Priority Mail' },
+  { value: 'dhl', label: 'DHL Express' },
+];
+
+/** Stands in for a request to the shipping rates API. */
+const fetchCarriers = () =>
+  new Promise<MultiSelectOption[]>((resolve) => setTimeout(() => resolve(CARRIERS), 1500));
+
+@Component({
+  selector: 'app-multi-select-loading',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlMultiSelect, SlMultiSelectItem],
+  template: `
+    <div slField>
+      <label slFieldLabel>Carriers offered at checkout</label>
+      <sl-multi-select
+        placeholder="Add a carrier"
+        [loading]="loading()"
+        [items]="carriers()"
+        [messages]="{ loading: 'Fetching carriers…' }"
+        (openChange)="load($event)"
+      >
+        @for (carrier of carriers(); track carrier.value) {
+          <sl-multi-select-item [value]="carrier.value" [label]="carrier.label" />
+        }
+      </sl-multi-select>
+      <span slFieldDescription>Carriers load from the rates service when the list opens.</span>
+    </div>
+  `,
+})
+export class MultiSelectLoading {
+  protected readonly carriers = signal<MultiSelectOption[]>([]);
+  protected readonly loading = signal(false);
+  private loaded = false;
+
+  protected async load(open: boolean): Promise<void> {
+    if (!open || this.loaded || this.loading()) return;
+    this.loading.set(true);
+    this.carriers.set(await fetchCarriers());
+    this.loading.set(false);
+    this.loaded = true;
+  }
+}
+```
+
+### long-list.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import {
+  SlMultiSelect,
+  SlMultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/angular/multi-select';
+
+const STATES: MultiSelectOption[] = [
+  { value: 'AL', label: 'Alabama' },
+  { value: 'AK', label: 'Alaska' },
+  { value: 'AZ', label: 'Arizona' },
+  { value: 'AR', label: 'Arkansas' },
+  { value: 'CA', label: 'California' },
+  { value: 'CO', label: 'Colorado' },
+  { value: 'CT', label: 'Connecticut' },
+  { value: 'DE', label: 'Delaware' },
+  { value: 'FL', label: 'Florida' },
+  { value: 'GA', label: 'Georgia' },
+  { value: 'HI', label: 'Hawaii' },
+  { value: 'ID', label: 'Idaho' },
+  { value: 'IL', label: 'Illinois' },
+  { value: 'IN', label: 'Indiana' },
+  { value: 'IA', label: 'Iowa' },
+  { value: 'KS', label: 'Kansas' },
+  { value: 'KY', label: 'Kentucky' },
+  { value: 'LA', label: 'Louisiana' },
+  { value: 'ME', label: 'Maine' },
+  { value: 'MD', label: 'Maryland' },
+  { value: 'MA', label: 'Massachusetts' },
+  { value: 'MI', label: 'Michigan' },
+  { value: 'MN', label: 'Minnesota' },
+  { value: 'MS', label: 'Mississippi' },
+  { value: 'MO', label: 'Missouri' },
+  { value: 'MT', label: 'Montana' },
+  { value: 'NE', label: 'Nebraska' },
+  { value: 'NV', label: 'Nevada' },
+  { value: 'NH', label: 'New Hampshire' },
+  { value: 'NJ', label: 'New Jersey' },
+  { value: 'NM', label: 'New Mexico' },
+  { value: 'NY', label: 'New York' },
+  { value: 'NC', label: 'North Carolina' },
+  { value: 'ND', label: 'North Dakota' },
+  { value: 'OH', label: 'Ohio' },
+  { value: 'OK', label: 'Oklahoma' },
+  { value: 'OR', label: 'Oregon' },
+  { value: 'PA', label: 'Pennsylvania' },
+  { value: 'RI', label: 'Rhode Island' },
+  { value: 'SC', label: 'South Carolina' },
+  { value: 'SD', label: 'South Dakota' },
+  { value: 'TN', label: 'Tennessee' },
+  { value: 'TX', label: 'Texas' },
+  { value: 'UT', label: 'Utah' },
+  { value: 'VT', label: 'Vermont' },
+  { value: 'VA', label: 'Virginia' },
+  { value: 'WA', label: 'Washington' },
+  { value: 'WV', label: 'West Virginia' },
+  { value: 'WI', label: 'Wisconsin' },
+  { value: 'WY', label: 'Wyoming' },
+];
+
+@Component({
+  selector: 'app-multi-select-long-list',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlMultiSelect, SlMultiSelectItem],
+  template: `
+    <div slField>
+      <label slFieldLabel>Ship-to states</label>
+      <sl-multi-select
+        chosenOptions="hide"
+        placeholder="Add a state"
+        [items]="states"
+        [value]="shipTo"
+      >
+        @for (state of states; track state.value) {
+          <sl-multi-select-item [value]="state.value" [label]="state.label" />
+        }
+      </sl-multi-select>
+      <span slFieldDescription
+        >Ground shipping from Reno, NV reaches these states in two days.</span
+      >
+    </div>
+  `,
+})
+export class MultiSelectLongList {
+  protected readonly states = STATES;
+  protected readonly shipTo = ['CA', 'NV', 'OR'];
+}
+```
+
+### narrow.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import {
+  SlMultiSelect,
+  SlMultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/angular/multi-select';
+import { SlStack } from '@slotted/angular/stack';
+
+const CHANNELS: MultiSelectOption[] = [
+  { value: 'web', label: 'Web store' },
+  { value: 'marketplace', label: 'Marketplace' },
+  { value: 'wholesale', label: 'Wholesale' },
+  { value: 'phone', label: 'Phone orders' },
+];
+
+@Component({
+  selector: 'app-multi-select-narrow',
+  imports: [SlField, SlFieldLabel, SlMultiSelect, SlMultiSelectItem, SlStack],
+  template: `
+    <div slStack [gap]="4" style="inline-size: 7rem">
+      <div slField>
+        <label slFieldLabel>Channels</label>
+        <sl-multi-select size="sm" width="content" [items]="channels" [value]="chosen">
+          @for (channel of channels; track channel.value) {
+            <sl-multi-select-item [value]="channel.value" [label]="channel.label" />
+          }
+        </sl-multi-select>
+      </div>
+    </div>
+  `,
+})
+export class MultiSelectNarrow {
+  protected readonly channels = CHANNELS;
+  protected readonly chosen = ['web', 'marketplace', 'wholesale'];
+}
+```
+
+### order-tags.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import {
+  SlMultiSelect,
+  SlMultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/angular/multi-select';
+import {
+  SlTable,
+  SlTableBody,
+  SlTableCell,
+  SlTableColumnHeader,
+  SlTableContent,
+  SlTableHead,
+  SlTableRow,
+  SlTableRowHeader,
+} from '@slotted/angular/table';
+
+const TAGS: MultiSelectOption[] = [
+  { value: 'priority', label: 'priority' },
+  { value: 'gift wrap', label: 'gift wrap' },
+  { value: 'fragile', label: 'fragile' },
+  { value: 'backorder', label: 'backorder' },
+  { value: 'address check', label: 'address check' },
+  { value: 'wholesale', label: 'wholesale' },
+];
+
+const ORDERS = [
+  { id: 'SO-10482', customer: 'Harbor & Pine', tags: ['priority', 'fragile'] },
+  { id: 'SO-10483', customer: 'Brightline Studio', tags: ['address check'] },
+  { id: 'SO-10484', customer: 'Northgate Labs', tags: ['wholesale', 'backorder', 'priority'] },
+  { id: 'SO-10485', customer: 'Verde Kitchen', tags: [] },
+];
+
+@Component({
+  selector: 'app-multi-select-order-tags',
+  imports: [
+    SlMultiSelect,
+    SlMultiSelectItem,
+    SlTable,
+    SlTableBody,
+    SlTableCell,
+    SlTableColumnHeader,
+    SlTableContent,
+    SlTableHead,
+    SlTableRow,
+    SlTableRowHeader,
+  ],
+  template: `
+    <div slTable [columns]="3">
+      <div slTableContent aria-label="Orders">
+        <thead slTableHead>
+          <tr slTableRow>
+            <th slTableColumnHeader>Order</th>
+            <th slTableColumnHeader>Customer</th>
+            <th slTableColumnHeader>Tags</th>
+          </tr>
+        </thead>
+        <tbody slTableBody>
+          @for (order of orders; track order.id) {
+            <tr slTableRow [value]="order.id">
+              <th slTableRowHeader>{{ order.id }}</th>
+              <td slTableCell>{{ order.customer }}</td>
+              <td slTableCell>
+                <sl-multi-select
+                  variant="plain"
+                  size="sm"
+                  overflow="collapse"
+                  creatable
+                  placeholder="Add a tag"
+                  [aria-label]="'Tags for ' + order.id"
+                  [items]="tags"
+                  [value]="order.tags"
+                >
+                  @for (tag of tags; track tag.value) {
+                    <sl-multi-select-item [value]="tag.value" [label]="tag.label" />
+                  }
+                </sl-multi-select>
+              </td>
+            </tr>
+          }
+        </tbody>
+      </div>
+    </div>
+  `,
+})
+export class MultiSelectOrderTags {
+  protected readonly tags = TAGS;
+  protected readonly orders = ORDERS;
+}
+```