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

package/dist/docs/multi-select.examples.md

@@ -0,0 +1,1867 @@
+<!-- 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
+
+```tsx
+<MultiSelect defaultValue={['checkout-api']}>
+  <MultiSelectControl aria-label="Affected services" placeholder="Add a service" />
+  <MultiSelectContent aria-label="Affected services">
+    <MultiSelectItem value="checkout-api">checkout-api</MultiSelectItem>
+    <MultiSelectItem value="payments-worker">payments-worker</MultiSelectItem>
+  </MultiSelectContent>
+</MultiSelect>;
+```
+
+### 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
+
+```tsx
+const [services, setServices] = useState(['checkout-api', 'payments-worker']);
+
+<MultiSelect onValueChange={setServices} value={services}>
+  <MultiSelectControl aria-label="Affected services" />
+  <MultiSelectContent aria-label="Affected services">…</MultiSelectContent>
+</MultiSelect>;
+```
+
+### 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
+
+```tsx
+<MultiSelect
+  creatable
+  onValueChange={(labels, request) => {
+    if (request.reason === 'submit') report(labels);
+  }}
+>
+  <MultiSelectControl aria-label="Labels" placeholder="Add a label" />
+  <MultiSelectContent aria-label="Labels">…</MultiSelectContent>
+</MultiSelect>;
+```
+
+### 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 onValueRefuse instead of vanishing.
+
+Example
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import {
+  MultiSelect,
+  MultiSelectContent,
+  MultiSelectControl,
+  MultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/react/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' },
+];
+
+export default function MultiSelectLimit() {
+  return (
+    <Field>
+      <FieldLabel>Featured categories</FieldLabel>
+      <MultiSelect max={3} defaultValue={['beverages', 'confections']} items={CATEGORIES}>
+        <MultiSelectControl placeholder="Add a category" />
+        <MultiSelectContent>
+          {CATEGORIES.map((category) => (
+            <MultiSelectItem key={category.value} value={category.value}>
+              {category.label}
+            </MultiSelectItem>
+          ))}
+        </MultiSelectContent>
+      </MultiSelect>
+      <FieldDescription>The storefront home page shows up to three categories.</FieldDescription>
+    </Field>
+  );
+}
+```
+
+### 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
+
+```tsx
+<MultiSelect creatable locale="pt-BR">
+  …
+</MultiSelect>;
+
+<MultiSelect allowDuplicates creatable>
+  …
+</MultiSelect>;
+```
+
+### 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
+
+```tsx
+<MultiSelect
+  onValueChange={(order, request) => {
+    if (request.reason === 'keyboard') saveOrder(order);
+  }}
+  reorderable
+>
+  <MultiSelectControl aria-label="Runbook steps" />
+  <MultiSelectContent aria-label="Runbook steps">…</MultiSelectContent>
+</MultiSelect>;
+```
+
+### 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
+
+```tsx
+<MultiSelect addOnPaste creatable delimiters={[',', ';']} max={5}>
+  <MultiSelectControl aria-label="Notify" placeholder="Paste a list" />
+  <MultiSelectContent aria-label="Notify">…</MultiSelectContent>
+</MultiSelect>;
+```
+
+### 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
+
+```tsx
+<MultiSelect creatable editable defaultValue={['payments-worker']}>
+  <MultiSelectControl aria-label="Labels" />
+  <MultiSelectContent aria-label="Labels">…</MultiSelectContent>
+</MultiSelect>;
+```
+
+### 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
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import {
+  MultiSelect,
+  MultiSelectContent,
+  MultiSelectControl,
+  MultiSelectItem,
+} from '@slotted/react/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' },
+];
+
+export default function MultiSelectFiltering() {
+  return (
+    <Field>
+      <FieldLabel>Distributor cities</FieldLabel>
+      <MultiSelect>
+        <MultiSelectControl placeholder="Search cities" />
+        <MultiSelectContent>
+          {CITIES.map((city) => (
+            <MultiSelectItem key={city.value} value={city.value}>
+              {city.label}
+            </MultiSelectItem>
+          ))}
+        </MultiSelectContent>
+      </MultiSelect>
+      <FieldDescription>Type “zur” or “malmo”: accents and case are ignored.</FieldDescription>
+    </Field>
+  );
+}
+```
+
+### 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
+
+```tsx
+import { Fragment } from 'react';
+import { Field, FieldLabel } from '@slotted/react/field';
+import {
+  MultiSelect,
+  MultiSelectContent,
+  MultiSelectControl,
+  MultiSelectGroup,
+  MultiSelectItem,
+  type MultiSelectOptionGroup,
+  MultiSelectSeparator,
+} from '@slotted/react/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' },
+    ],
+  },
+];
+
+export default function MultiSelectGroups() {
+  return (
+    <Field>
+      <FieldLabel>Stocking warehouses</FieldLabel>
+      <MultiSelect defaultValue={['RNO', 'SAV']} items={REGIONS}>
+        <MultiSelectControl placeholder="Add a warehouse" />
+        <MultiSelectContent>
+          {REGIONS.map((region, index) => (
+            <Fragment key={region.label}>
+              {index > 0 && <MultiSelectSeparator />}
+              <MultiSelectGroup label={region.label}>
+                {region.options.map((warehouse) => (
+                  <MultiSelectItem key={warehouse.value} value={warehouse.value}>
+                    {warehouse.label}
+                  </MultiSelectItem>
+                ))}
+              </MultiSelectGroup>
+            </Fragment>
+          ))}
+        </MultiSelectContent>
+      </MultiSelect>
+    </Field>
+  );
+}
+```
+
+### 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
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import {
+  MultiSelect,
+  MultiSelectContent,
+  MultiSelectControl,
+  MultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/react/multi-select';
+import { Stack } from '@slotted/react/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'];
+
+const options = WAREHOUSES.map((warehouse) => (
+  <MultiSelectItem key={warehouse.value} value={warehouse.value}>
+    {warehouse.label}
+  </MultiSelectItem>
+));
+
+export default function MultiSelectOverflow() {
+  return (
+    <Stack gap={5}>
+      <Field>
+        <FieldLabel>Stocking warehouses</FieldLabel>
+        <MultiSelect overflow="wrap" defaultValue={STOCKED} items={WAREHOUSES}>
+          <MultiSelectControl />
+          <MultiSelectContent>{options}</MultiSelectContent>
+        </MultiSelect>
+        <FieldDescription>Wrap: every chip stays in view, up to three rows.</FieldDescription>
+      </Field>
+      <Field>
+        <FieldLabel>Stocking warehouses</FieldLabel>
+        <MultiSelect overflow="collapse" defaultValue={STOCKED} items={WAREHOUSES}>
+          <MultiSelectControl />
+          <MultiSelectContent>{options}</MultiSelectContent>
+        </MultiSelect>
+        <FieldDescription>Collapse: one row, and a count of the rest.</FieldDescription>
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### 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
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import {
+  MultiSelect,
+  MultiSelectContent,
+  MultiSelectControl,
+  MultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/react/multi-select';
+import { Stack } from '@slotted/react/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;
+
+export default function MultiSelectSizes() {
+  return (
+    <Stack gap={5}>
+      {SIZES.map(({ size, label }) => (
+        <Field key={size} size={size}>
+          <FieldLabel>{label}</FieldLabel>
+          <MultiSelect defaultValue={['RNO', 'CMH']} items={WAREHOUSES}>
+            <MultiSelectControl />
+            <MultiSelectContent>
+              {WAREHOUSES.map((warehouse) => (
+                <MultiSelectItem key={warehouse.value} value={warehouse.value}>
+                  {warehouse.label}
+                </MultiSelectItem>
+              ))}
+            </MultiSelectContent>
+          </MultiSelect>
+        </Field>
+      ))}
+    </Stack>
+  );
+}
+```
+
+### 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
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import {
+  MultiSelect,
+  MultiSelectContent,
+  MultiSelectControl,
+  MultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/react/multi-select';
+import { Stack } from '@slotted/react/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;
+
+export default function MultiSelectVariants() {
+  return (
+    <Stack gap={5}>
+      {VARIANTS.map(({ variant, label }) => (
+        <Field key={variant}>
+          <FieldLabel>{label}</FieldLabel>
+          <MultiSelect variant={variant} defaultValue={['web', 'wholesale']} items={CHANNELS}>
+            <MultiSelectControl />
+            <MultiSelectContent>
+              {CHANNELS.map((channel) => (
+                <MultiSelectItem key={channel.value} value={channel.value}>
+                  {channel.label}
+                </MultiSelectItem>
+              ))}
+            </MultiSelectContent>
+          </MultiSelect>
+        </Field>
+      ))}
+    </Stack>
+  );
+}
+```
+
+### 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
+
+```tsx
+import { Field, FieldDescription, FieldError, FieldLabel } from '@slotted/react/field';
+import {
+  MultiSelect,
+  MultiSelectContent,
+  MultiSelectControl,
+  MultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/react/multi-select';
+import { Stack } from '@slotted/react/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 options = WAREHOUSES.map((warehouse) => (
+  <MultiSelectItem key={warehouse.value} value={warehouse.value}>
+    {warehouse.label}
+  </MultiSelectItem>
+));
+
+export default function MultiSelectStates() {
+  return (
+    <Stack gap={5}>
+      <Field invalid required>
+        <FieldLabel>Stocking warehouses</FieldLabel>
+        <MultiSelect items={WAREHOUSES}>
+          <MultiSelectControl placeholder="Add a warehouse" />
+          <MultiSelectContent>{options}</MultiSelectContent>
+        </MultiSelect>
+        <FieldError>Choose at least one warehouse before publishing.</FieldError>
+      </Field>
+      <Field readOnly>
+        <FieldLabel>Warehouses holding stock</FieldLabel>
+        <MultiSelect defaultValue={['RNO', 'SAV']} items={WAREHOUSES}>
+          <MultiSelectControl />
+          <MultiSelectContent>{options}</MultiSelectContent>
+        </MultiSelect>
+        <FieldDescription>Updated by the nightly inventory sync.</FieldDescription>
+      </Field>
+      <Field disabled>
+        <FieldLabel>Transfer warehouses</FieldLabel>
+        <MultiSelect defaultValue={['CMH']} items={WAREHOUSES}>
+          <MultiSelectControl />
+          <MultiSelectContent>{options}</MultiSelectContent>
+        </MultiSelect>
+        <FieldDescription>Transfers open once the purchase order is received.</FieldDescription>
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### 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
+
+```tsx
+<MultiSelect loading>…</MultiSelect>;
+
+<MultiSelectContent 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
+
+```tsx
+<MultiSelect defaultValue={['notification-relay-eu-west-1-canary']}>
+  <MultiSelectControl aria-label="Affected services" />
+  <MultiSelectContent aria-label="Affected services">…</MultiSelectContent>
+</MultiSelect>;
+```
+
+### 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
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import {
+  MultiSelect,
+  MultiSelectContent,
+  MultiSelectControl,
+  MultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/react/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' },
+];
+
+export default function MultiSelectKeyboard() {
+  return (
+    <Field>
+      <FieldLabel>Carrier priority</FieldLabel>
+      <MultiSelect reorderable defaultValue={['usps', 'ups', 'fedex']} items={CARRIERS}>
+        <MultiSelectControl placeholder="Add a carrier" />
+        <MultiSelectContent>
+          {CARRIERS.map((carrier) => (
+            <MultiSelectItem key={carrier.value} value={carrier.value}>
+              {carrier.label}
+            </MultiSelectItem>
+          ))}
+        </MultiSelectContent>
+      </MultiSelect>
+      <FieldDescription>
+        Rates are requested from the first carrier, then the next. Alt with an arrow moves the
+        focused carrier.
+      </FieldDescription>
+    </Field>
+  );
+}
+```
+
+### In a form
+
+One hidden input per value, all under the same name, so a plain FormData receives several values under one key and a native reset() restores them. The field carries the label, the description and the error by ID.
+
+Example
+
+```tsx
+import { useState } from 'react';
+import type { SubmitEvent } from 'react';
+import { Button } from '@slotted/react/button';
+import { Field, FieldError, FieldLabel } from '@slotted/react/field';
+import { Inline } from '@slotted/react/inline';
+import {
+  MultiSelect,
+  MultiSelectContent,
+  MultiSelectControl,
+  MultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/react/multi-select';
+import { Stack } from '@slotted/react/stack';
+import { Text } from '@slotted/react/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' },
+];
+
+export default function MultiSelectForm() {
+  const [missing, setMissing] = useState(false);
+  const [saved, setSaved] = useState<string | null>(null);
+
+  const submit = (event: SubmitEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const data = new FormData(event.currentTarget);
+    const warehouses = data.getAll('warehouses');
+    setMissing(warehouses.length === 0);
+    setSaved(
+      warehouses.length === 0
+        ? null
+        : `Saved with ${warehouses.length} of ${WAREHOUSES.length} warehouses.`,
+    );
+  };
+
+  const reset = () => {
+    setMissing(false);
+    setSaved(null);
+  };
+
+  return (
+    <form noValidate onSubmit={submit} onReset={reset}>
+      <Stack gap={5}>
+        <Field required invalid={missing ? true : undefined}>
+          <FieldLabel>Stocking warehouses</FieldLabel>
+          <MultiSelect name="warehouses" items={WAREHOUSES} onValueChange={() => setMissing(false)}>
+            <MultiSelectControl placeholder="Add a warehouse" />
+            <MultiSelectContent>
+              {WAREHOUSES.map((warehouse) => (
+                <MultiSelectItem key={warehouse.value} value={warehouse.value}>
+                  {warehouse.label}
+                </MultiSelectItem>
+              ))}
+            </MultiSelectContent>
+          </MultiSelect>
+          <FieldError live="polite" reserve>
+            {missing ? 'Choose at least one warehouse to stock this product.' : ''}
+          </FieldError>
+        </Field>
+        <Field>
+          <FieldLabel>Sales channels</FieldLabel>
+          <MultiSelect name="channels" defaultValue={['web']} items={CHANNELS}>
+            <MultiSelectControl />
+            <MultiSelectContent>
+              {CHANNELS.map((channel) => (
+                <MultiSelectItem key={channel.value} value={channel.value}>
+                  {channel.label}
+                </MultiSelectItem>
+              ))}
+            </MultiSelectContent>
+          </MultiSelect>
+        </Field>
+        <Inline gap={3} align="center">
+          <Button type="submit">Save</Button>
+          <Button type="reset" tone="secondary" variant="outline">
+            Reset
+          </Button>
+          {saved && (
+            <Text size="sm" tone="muted">
+              {saved}
+            </Text>
+          )}
+        </Inline>
+      </Stack>
+    </form>
+  );
+}
+```
+
+### Composition, and the defaults an application sets once
+
+A provider carries the axes, the words come from the language in force, render replaces the frame while keeping the measurement, and the handle answers the actions a prop cannot express.
+
+Excerpt — not a complete module
+
+```tsx
+<MultiSelectDefaultsProvider size="sm" variant="subtle">
+  <MultiSelect ref={handle}>
+    <MultiSelectControl render={(props) => <fieldset {...props} />} />
+    <MultiSelectContent aria-label="Affected services">…</MultiSelectContent>
+  </MultiSelect>
+</MultiSelectDefaultsProvider>;
+```
+
+### async-search.tsx
+
+Example
+
+```tsx
+import { useEffect, useState } from 'react';
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import {
+  MultiSelect,
+  MultiSelectContent,
+  MultiSelectControl,
+  MultiSelectItem,
+} from '@slotted/react/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);
+
+export default function MultiSelectAsyncSearch() {
+  const [query, setQuery] = useState('');
+  const [results, setResults] = useState<Customer[]>(FIRST_PAGE);
+  const [loading, setLoading] = useState(false);
+
+  useEffect(() => {
+    if (query.trim() === '') {
+      setResults(FIRST_PAGE);
+      setLoading(false);
+      return;
+    }
+    let current = true;
+    setLoading(true);
+    void searchCustomers(query).then((found) => {
+      if (!current) return;
+      setResults(found);
+      setLoading(false);
+    });
+    return () => {
+      current = false;
+    };
+  }, [query]);
+
+  return (
+    <Field>
+      <FieldLabel>Customers in this campaign</FieldLabel>
+      <MultiSelect
+        filter={null}
+        loading={loading}
+        messages={{ empty: 'No customer by that name.', loading: 'Searching customers…' }}
+        onInputValueChange={setQuery}
+      >
+        <MultiSelectControl placeholder="Search customers" />
+        <MultiSelectContent>
+          {results.map((customer) => (
+            <MultiSelectItem
+              key={customer.value}
+              value={customer.value}
+              description={customer.city}
+            >
+              {customer.label}
+            </MultiSelectItem>
+          ))}
+        </MultiSelectContent>
+      </MultiSelect>
+      <FieldDescription>Each keystroke searches the customer list on the server.</FieldDescription>
+    </Field>
+  );
+}
+```
+
+### choose-columns.tsx
+
+Example
+
+```tsx
+import { useState } from 'react';
+import { Button } from '@slotted/react/button';
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import { Inline } from '@slotted/react/inline';
+import {
+  MultiSelect,
+  MultiSelectContent,
+  MultiSelectControl,
+  MultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/react/multi-select';
+import { Stack } from '@slotted/react/stack';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableColumnHeader,
+  TableContent,
+  TableHead,
+  TableRow,
+} from '@slotted/react/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;
+
+export default function MultiSelectChooseColumns() {
+  const [shown, setShown] = useState<readonly string[]>(['order', 'customer', 'total']);
+  const columns = shown as readonly Column[];
+
+  return (
+    <Stack gap={4}>
+      <Field>
+        <Inline gap={3} justify="between" align="center">
+          <FieldLabel>Columns</FieldLabel>
+          <Button
+            size="sm"
+            tone="secondary"
+            variant="ghost"
+            disabled={shown.length === ALL.length}
+            onClick={() => setShown(ALL)}
+          >
+            Show all
+          </Button>
+        </Inline>
+        <MultiSelect reorderable value={shown} items={COLUMNS} onValueChange={setShown}>
+          <MultiSelectControl placeholder="Add a column" />
+          <MultiSelectContent>
+            {COLUMNS.map((column) => (
+              <MultiSelectItem key={column.value} value={column.value}>
+                {column.label}
+              </MultiSelectItem>
+            ))}
+          </MultiSelectContent>
+        </MultiSelect>
+        <FieldDescription>
+          The table follows the order of the chips. Alt with an arrow moves a focused column.
+        </FieldDescription>
+      </Field>
+      <Table columns={Math.max(columns.length, 1)}>
+        <TableContent aria-label="Orders">
+          <TableHead>
+            <TableRow>
+              {columns.map((column) => (
+                <TableColumnHeader key={column}>{labelOf(column)}</TableColumnHeader>
+              ))}
+            </TableRow>
+          </TableHead>
+          <TableBody>
+            {ORDERS.map((order) => (
+              <TableRow key={order.order} value={order.order}>
+                {columns.map((column) => (
+                  <TableCell key={column}>{order[column]}</TableCell>
+                ))}
+              </TableRow>
+            ))}
+          </TableBody>
+        </TableContent>
+      </Table>
+    </Stack>
+  );
+}
+```
+
+### clearing.tsx
+
+Example
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import {
+  MultiSelect,
+  MultiSelectContent,
+  MultiSelectControl,
+  MultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/react/multi-select';
+import { Stack } from '@slotted/react/stack';
+
+const CHANNELS: MultiSelectOption[] = [
+  { value: 'web', label: 'Web store' },
+  { value: 'marketplace', label: 'Marketplace' },
+  { value: 'wholesale', label: 'Wholesale' },
+  { value: 'phone', label: 'Phone orders' },
+];
+
+const options = CHANNELS.map((channel) => (
+  <MultiSelectItem key={channel.value} value={channel.value}>
+    {channel.label}
+  </MultiSelectItem>
+));
+
+export default function MultiSelectClearing() {
+  return (
+    <Stack gap={5}>
+      <Field>
+        <FieldLabel>Show orders from</FieldLabel>
+        <MultiSelect defaultValue={['web', 'marketplace', 'phone']} items={CHANNELS}>
+          <MultiSelectControl placeholder="All channels" />
+          <MultiSelectContent>{options}</MultiSelectContent>
+        </MultiSelect>
+        <FieldDescription>The clear button empties the filter in one press.</FieldDescription>
+      </Field>
+      <Field>
+        <FieldLabel>Sell through</FieldLabel>
+        <MultiSelect clearable={false} defaultValue={['web', 'wholesale']} items={CHANNELS}>
+          <MultiSelectControl />
+          <MultiSelectContent>{options}</MultiSelectContent>
+        </MultiSelect>
+        <FieldDescription>No clear button: channels come off one at a time.</FieldDescription>
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### controlled.tsx
+
+Example
+
+```tsx
+import { useState } from 'react';
+import { Field, FieldLabel } from '@slotted/react/field';
+import {
+  MultiSelect,
+  MultiSelectContent,
+  MultiSelectControl,
+  MultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/react/multi-select';
+import { Stack } from '@slotted/react/stack';
+import { Text } from '@slotted/react/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;
+
+export default function MultiSelectControlled() {
+  const [warehouses, setWarehouses] = useState<readonly string[]>(['RNO', 'CMH']);
+  const [reason, setReason] = useState<string | null>(null);
+
+  return (
+    <Stack gap={3}>
+      <Field>
+        <FieldLabel>Stocking warehouses</FieldLabel>
+        <MultiSelect
+          value={warehouses}
+          items={WAREHOUSES}
+          onValueChange={(next, request) => {
+            setWarehouses(next);
+            setReason(request.reason);
+          }}
+        >
+          <MultiSelectControl placeholder="Add a warehouse" />
+          <MultiSelectContent>
+            {WAREHOUSES.map((warehouse) => (
+              <MultiSelectItem key={warehouse.value} value={warehouse.value}>
+                {warehouse.label}
+              </MultiSelectItem>
+            ))}
+          </MultiSelectContent>
+        </MultiSelect>
+      </Field>
+      <Text size="sm" tone="muted">
+        {warehouses.length === 0
+          ? 'Not stocked anywhere'
+          : `Stocked at ${warehouses.map(labelOf).join('; ')}`}
+        {reason === null ? '' : ` · last change: ${reason}`}
+      </Text>
+    </Stack>
+  );
+}
+```
+
+### creatable.tsx
+
+Example
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import {
+  MultiSelect,
+  MultiSelectContent,
+  MultiSelectControl,
+  MultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/react/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' },
+];
+
+export default function MultiSelectCreatable() {
+  return (
+    <Field>
+      <FieldLabel>Search keywords</FieldLabel>
+      <MultiSelect creatable defaultValue={['chai', 'black tea']} items={SUGGESTED}>
+        <MultiSelectControl placeholder="Add a keyword" />
+        <MultiSelectContent>
+          {SUGGESTED.map((keyword) => (
+            <MultiSelectItem key={keyword.value} value={keyword.value}>
+              {keyword.label}
+            </MultiSelectItem>
+          ))}
+        </MultiSelectContent>
+      </MultiSelect>
+      <FieldDescription>
+        Type a keyword and press Enter or a comma. Shoppers find Chai tea, 24 bags by these words.
+      </FieldDescription>
+    </Field>
+  );
+}
+```
+
+### defaults.tsx
+
+Example
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import {
+  MultiSelect,
+  MultiSelectContent,
+  MultiSelectControl,
+  MultiSelectDefaultsProvider,
+  MultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/react/multi-select';
+import { Stack } from '@slotted/react/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' },
+];
+
+export default function MultiSelectDefaults() {
+  return (
+    <MultiSelectDefaultsProvider size="sm" variant="subtle" overflow="collapse">
+      <Stack gap={4}>
+        <Field>
+          <FieldLabel>Account owners</FieldLabel>
+          <MultiSelect defaultValue={['lucia', 'kenji']} items={OWNERS}>
+            <MultiSelectControl placeholder="Any owner" />
+            <MultiSelectContent>
+              {OWNERS.map((owner) => (
+                <MultiSelectItem key={owner.value} value={owner.value}>
+                  {owner.label}
+                </MultiSelectItem>
+              ))}
+            </MultiSelectContent>
+          </MultiSelect>
+        </Field>
+        <Field>
+          <FieldLabel>Segments</FieldLabel>
+          <MultiSelect defaultValue={['wholesale']} items={SEGMENTS}>
+            <MultiSelectControl placeholder="Any segment" />
+            <MultiSelectContent>
+              {SEGMENTS.map((segment) => (
+                <MultiSelectItem key={segment.value} value={segment.value}>
+                  {segment.label}
+                </MultiSelectItem>
+              ))}
+            </MultiSelectContent>
+          </MultiSelect>
+        </Field>
+      </Stack>
+    </MultiSelectDefaultsProvider>
+  );
+}
+```
+
+### descriptions.tsx
+
+Example
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Glyph, type GlyphName, Icon } from '@slotted/react/icon';
+import {
+  MultiSelect,
+  MultiSelectContent,
+  MultiSelectControl,
+  MultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/react/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',
+  },
+];
+
+export default function MultiSelectDescriptions() {
+  return (
+    <Field>
+      <FieldLabel>Attach to the shipping email</FieldLabel>
+      <MultiSelect defaultValue={['invoice']} items={DOCUMENTS}>
+        <MultiSelectControl placeholder="Add a document" />
+        <MultiSelectContent>
+          {DOCUMENTS.map((document) => (
+            <MultiSelectItem
+              key={document.value}
+              value={document.value}
+              description={document.description}
+              icon={
+                <Icon>
+                  <Glyph name={document.icon} />
+                </Icon>
+              }
+            >
+              {document.label}
+            </MultiSelectItem>
+          ))}
+        </MultiSelectContent>
+      </MultiSelect>
+    </Field>
+  );
+}
+```
+
+### disabled-options.tsx
+
+Example
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import {
+  MultiSelect,
+  MultiSelectContent,
+  MultiSelectControl,
+  MultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/react/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,
+  },
+];
+
+export default function MultiSelectDisabledOptions() {
+  return (
+    <Field>
+      <FieldLabel>Receiving warehouses</FieldLabel>
+      <MultiSelect defaultValue={['RNO']} items={WAREHOUSES}>
+        <MultiSelectControl placeholder="Add a warehouse" />
+        <MultiSelectContent>
+          {WAREHOUSES.map((warehouse) => (
+            <MultiSelectItem
+              key={warehouse.value}
+              value={warehouse.value}
+              description={warehouse.description}
+              disabled={warehouse.disabled ?? false}
+            >
+              {warehouse.label}
+            </MultiSelectItem>
+          ))}
+        </MultiSelectContent>
+      </MultiSelect>
+    </Field>
+  );
+}
+```
+
+### editable.tsx
+
+Example
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import { MultiSelect, MultiSelectContent, MultiSelectControl } from '@slotted/react/multi-select';
+
+export default function MultiSelectEditable() {
+  return (
+    <Field>
+      <FieldLabel>Bin locations</FieldLabel>
+      <MultiSelect
+        creatable
+        editable
+        defaultValue={['A-12-03', 'A-12-04', 'C-02-11']}
+        messages={{ empty: 'Type a bin code and press Enter.' }}
+      >
+        <MultiSelectControl placeholder="Add a bin" />
+        <MultiSelectContent />
+      </MultiSelect>
+      <FieldDescription>
+        Press ArrowLeft to reach a bin, then Enter to correct it in place.
+      </FieldDescription>
+    </Field>
+  );
+}
+```
+
+### email-list.tsx
+
+Example
+
+```tsx
+import { useState } from 'react';
+import { Field, FieldDescription, FieldError, FieldLabel } from '@slotted/react/field';
+import {
+  MultiSelect,
+  MultiSelectContent,
+  MultiSelectControl,
+  MultiSelectItem,
+  type MultiSelectRefuseCause,
+} from '@slotted/react/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',
+};
+
+export default function MultiSelectEmailList() {
+  const [refused, setRefused] = useState<string | null>(null);
+
+  return (
+    <Field invalid={refused !== null ? true : undefined}>
+      <FieldLabel>Stockout alerts</FieldLabel>
+      <MultiSelect
+        creatable
+        delimiters={[',', ';', ' ']}
+        defaultValue={['purchasing@northwind.example']}
+        validateValue={isEmail}
+        onValueRefuse={(values, { cause }) => setRefused(`${values.join(', ')} ${REASONS[cause]}.`)}
+        onValueChange={() => setRefused(null)}
+      >
+        <MultiSelectControl placeholder="name@company.com" />
+        <MultiSelectContent>
+          {TEAMS.map((team) => (
+            <MultiSelectItem key={team.value} value={team.value} description={team.description}>
+              {team.value}
+            </MultiSelectItem>
+          ))}
+        </MultiSelectContent>
+      </MultiSelect>
+      {refused === null ? (
+        <FieldDescription>Paste a list separated by commas, semicolons or spaces.</FieldDescription>
+      ) : (
+        <FieldError live="polite">{refused}</FieldError>
+      )}
+    </Field>
+  );
+}
+```
+
+### filter-bar.tsx
+
+Example
+
+```tsx
+import { useState } from 'react';
+import { Grid } from '@slotted/react/grid';
+import {
+  MultiSelect,
+  MultiSelectContent,
+  MultiSelectControl,
+  MultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/react/multi-select';
+import { Stack } from '@slotted/react/stack';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableColumnHeader,
+  TableContent,
+  TableHead,
+  TableRow,
+  TableRowHeader,
+} from '@slotted/react/table';
+import { Text } from '@slotted/react/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`;
+};
+
+export default function MultiSelectFilterBar() {
+  const [statuses, setStatuses] = useState<readonly string[]>(['open', 'delayed']);
+  const [channels, setChannels] = useState<readonly string[]>([]);
+
+  const rows = ORDERS.filter(
+    (order) =>
+      (statuses.length === 0 || statuses.includes(order.status)) &&
+      (channels.length === 0 || channels.includes(order.channel)),
+  );
+
+  return (
+    <Stack gap={3}>
+      <Grid columns={2} gap={3}>
+        <MultiSelect
+          size="sm"
+          overflow="collapse"
+          value={statuses}
+          items={STATUSES}
+          onValueChange={setStatuses}
+        >
+          <MultiSelectControl aria-label="Status" placeholder="All statuses" />
+          <MultiSelectContent aria-label="Status">
+            {STATUSES.map((status) => (
+              <MultiSelectItem
+                key={status.value}
+                value={status.value}
+                description={countOf('status', status.value)}
+              >
+                {status.label}
+              </MultiSelectItem>
+            ))}
+          </MultiSelectContent>
+        </MultiSelect>
+        <MultiSelect
+          size="sm"
+          overflow="collapse"
+          value={channels}
+          items={CHANNELS}
+          onValueChange={setChannels}
+        >
+          <MultiSelectControl aria-label="Channel" placeholder="All channels" />
+          <MultiSelectContent aria-label="Channel">
+            {CHANNELS.map((channel) => (
+              <MultiSelectItem
+                key={channel.value}
+                value={channel.value}
+                description={countOf('channel', channel.value)}
+              >
+                {channel.label}
+              </MultiSelectItem>
+            ))}
+          </MultiSelectContent>
+        </MultiSelect>
+      </Grid>
+      <Text size="sm" tone="muted">
+        {rows.length} of {ORDERS.length} orders
+      </Text>
+      <Table columns={5}>
+        <TableContent aria-label="Orders">
+          <TableHead>
+            <TableRow>
+              <TableColumnHeader>Order</TableColumnHeader>
+              <TableColumnHeader>Customer</TableColumnHeader>
+              <TableColumnHeader>Status</TableColumnHeader>
+              <TableColumnHeader>Channel</TableColumnHeader>
+              <TableColumnHeader numeric>Total</TableColumnHeader>
+            </TableRow>
+          </TableHead>
+          <TableBody>
+            {rows.map((order) => (
+              <TableRow key={order.id} value={order.id}>
+                <TableRowHeader>{order.id}</TableRowHeader>
+                <TableCell>{order.customer}</TableCell>
+                <TableCell>{labelOf(STATUSES, order.status)}</TableCell>
+                <TableCell>{labelOf(CHANNELS, order.channel)}</TableCell>
+                <TableCell numeric>{order.total}</TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </TableContent>
+      </Table>
+    </Stack>
+  );
+}
+```
+
+### initial-value.tsx
+
+Example
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import {
+  MultiSelect,
+  MultiSelectContent,
+  MultiSelectControl,
+  MultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/react/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' },
+];
+
+export default function MultiSelectInitialValue() {
+  return (
+    <Field>
+      <FieldLabel>Stocking warehouses</FieldLabel>
+      <MultiSelect defaultValue={['RNO', 'CMH']} items={WAREHOUSES}>
+        <MultiSelectControl placeholder="Add a warehouse" />
+        <MultiSelectContent>
+          {WAREHOUSES.map((warehouse) => (
+            <MultiSelectItem key={warehouse.value} value={warehouse.value}>
+              {warehouse.label}
+            </MultiSelectItem>
+          ))}
+        </MultiSelectContent>
+      </MultiSelect>
+      <FieldDescription>Earl Grey, 100 bags is stocked at two warehouses.</FieldDescription>
+    </Field>
+  );
+}
+```
+
+### loading.tsx
+
+Example
+
+```tsx
+import { useState } from 'react';
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import {
+  MultiSelect,
+  MultiSelectContent,
+  MultiSelectControl,
+  MultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/react/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));
+
+export default function MultiSelectLoading() {
+  const [carriers, setCarriers] = useState<MultiSelectOption[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [loaded, setLoaded] = useState(false);
+
+  const load = async (open: boolean) => {
+    if (!open || loaded || loading) return;
+    setLoading(true);
+    setCarriers(await fetchCarriers());
+    setLoading(false);
+    setLoaded(true);
+  };
+
+  return (
+    <Field>
+      <FieldLabel>Carriers offered at checkout</FieldLabel>
+      <MultiSelect
+        loading={loading}
+        items={carriers}
+        messages={{ loading: 'Fetching carriers…' }}
+        onOpenChange={(open) => void load(open)}
+      >
+        <MultiSelectControl placeholder="Add a carrier" />
+        <MultiSelectContent>
+          {carriers.map((carrier) => (
+            <MultiSelectItem key={carrier.value} value={carrier.value}>
+              {carrier.label}
+            </MultiSelectItem>
+          ))}
+        </MultiSelectContent>
+      </MultiSelect>
+      <FieldDescription>Carriers load from the rates service when the list opens.</FieldDescription>
+    </Field>
+  );
+}
+```
+
+### long-list.tsx
+
+Example
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import {
+  MultiSelect,
+  MultiSelectContent,
+  MultiSelectControl,
+  MultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/react/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' },
+];
+
+export default function MultiSelectLongList() {
+  return (
+    <Field>
+      <FieldLabel>Ship-to states</FieldLabel>
+      <MultiSelect chosenOptions="hide" defaultValue={['CA', 'NV', 'OR']} items={STATES}>
+        <MultiSelectControl placeholder="Add a state" />
+        <MultiSelectContent>
+          {STATES.map((state) => (
+            <MultiSelectItem key={state.value} value={state.value}>
+              {state.label}
+            </MultiSelectItem>
+          ))}
+        </MultiSelectContent>
+      </MultiSelect>
+      <FieldDescription>
+        Ground shipping from Reno, NV reaches these states in two days.
+      </FieldDescription>
+    </Field>
+  );
+}
+```
+
+### narrow.tsx
+
+Example
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import {
+  MultiSelect,
+  MultiSelectContent,
+  MultiSelectControl,
+  MultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/react/multi-select';
+import { Stack } from '@slotted/react/stack';
+
+const CHANNELS: MultiSelectOption[] = [
+  { value: 'web', label: 'Web store' },
+  { value: 'marketplace', label: 'Marketplace' },
+  { value: 'wholesale', label: 'Wholesale' },
+  { value: 'phone', label: 'Phone orders' },
+];
+
+export default function MultiSelectNarrow() {
+  return (
+    <Stack gap={4} style={{ inlineSize: '7rem' }}>
+      <Field>
+        <FieldLabel>Channels</FieldLabel>
+        <MultiSelect
+          size="sm"
+          width="content"
+          defaultValue={['web', 'marketplace', 'wholesale']}
+          items={CHANNELS}
+        >
+          <MultiSelectControl />
+          <MultiSelectContent>
+            {CHANNELS.map((channel) => (
+              <MultiSelectItem key={channel.value} value={channel.value}>
+                {channel.label}
+              </MultiSelectItem>
+            ))}
+          </MultiSelectContent>
+        </MultiSelect>
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### order-tags.tsx
+
+Example
+
+```tsx
+import {
+  MultiSelect,
+  MultiSelectContent,
+  MultiSelectControl,
+  MultiSelectItem,
+  type MultiSelectOption,
+} from '@slotted/react/multi-select';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableColumnHeader,
+  TableContent,
+  TableHead,
+  TableRow,
+  TableRowHeader,
+} from '@slotted/react/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: [] },
+];
+
+export default function MultiSelectOrderTags() {
+  return (
+    <Table columns={3}>
+      <TableContent aria-label="Orders">
+        <TableHead>
+          <TableRow>
+            <TableColumnHeader>Order</TableColumnHeader>
+            <TableColumnHeader>Customer</TableColumnHeader>
+            <TableColumnHeader>Tags</TableColumnHeader>
+          </TableRow>
+        </TableHead>
+        <TableBody>
+          {ORDERS.map((order) => (
+            <TableRow key={order.id} value={order.id}>
+              <TableRowHeader>{order.id}</TableRowHeader>
+              <TableCell>{order.customer}</TableCell>
+              <TableCell>
+                <MultiSelect
+                  variant="plain"
+                  size="sm"
+                  overflow="collapse"
+                  creatable
+                  defaultValue={order.tags}
+                  items={TAGS}
+                >
+                  <MultiSelectControl aria-label={`Tags for ${order.id}`} placeholder="Add a tag" />
+                  <MultiSelectContent aria-label={`Tags for ${order.id}`}>
+                    {TAGS.map((tag) => (
+                      <MultiSelectItem key={tag.value} value={tag.value}>
+                        {tag.label}
+                      </MultiSelectItem>
+                    ))}
+                  </MultiSelectContent>
+                </MultiSelect>
+              </TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </TableContent>
+    </Table>
+  );
+}
+```