@neo4j-ndl/react 4.18.13 → 4.19.0

package/skills/ndl-react/components/combobox.md

@@ -0,0 +1,1487 @@
+# Combobox
+
+Import: `import { Combobox } from '@neo4j-ndl/react'`
+
+## Props
+
+### Combobox
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `actions` | `ComboboxAction[]` |  |  | Rows that act instead of selecting, pinned below the scrolling options after a divider so they stay visible however long the list is. They are always shown, never filtered by the search value, and never part of the selection. |
+| `autoComplete` | `string` |  |  | Hint for browser autofill on the native form control. |
+| `components` | `ComboboxComponents<TOption>` |  | `{}` | Replaces how selected values and option labels are presented, keeping the behavior and the ARIA of the combobox. |
+| `createOption` | `((searchValue: string) => TOption)` |  | `<TOption extends ComboboxOption>(   searchValue: string, ): TOption =>   ({     label: searchValue,     value: searchValue,   }) as TOption` | Builds the option to create from the search value. Defaults to using the search value as both label and value, which is only enough when the options carry no fields of their own beyond `ComboboxOption`. |
+| `defaultSearchValue` | `string` |  |  | The initial search value in uncontrolled mode. |
+| `defaultValue` | `ComboboxOption \| TOption[] \| null` |  |  | The initially selected option in uncontrolled mode. The initially selected options in uncontrolled mode. |
+| `errorText` | `ReactNode` |  |  | Error message below the control. Puts the control in its error state. |
+| `filterOption` | `ComboboxFilterOption<TOption>` |  |  | How options are matched against the search value. Defaults to a case-insensitive match on the option label. Pass `false` to skip internal filtering when the options are already filtered, such as when searching server side. |
+| `floatingStrategy` | `'absolute' \| 'fixed'` |  |  | Positioning strategy used by Floating UI. |
+| `formatCreateLabel` | `((searchValue: string) => ReactNode)` |  | `` (searchValue: string) =>   `Create "${searchValue}"` `` | Text of the create row. Defaults to `Create "<search value>"`. |
+| `formId` | `string` |  |  | Id of the form the combobox belongs to when it is outside that form. |
+| `hasRequiredIndicator` | `boolean` |  | `false` | Whether Required or Optional is shown at the end of the label row. |
+| `hasVisuallyHiddenLabel` | `boolean` |  | `false` | Whether the label is clipped out of the layout, leaving it to screen readers only. |
+| `helpText` | `ReactNode` |  |  | Assistive text below the control. Replaced by `errorText` while there is an error. |
+| `isClean` | `boolean` |  | `false` | Whether the control hugs its content without a background or resting outline. |
+| `isClearable` | `boolean` |  | `false` | Whether a button for clearing the selection is rendered in the trigger. |
+| `isCreatable` | `boolean` |  | `false` | Whether the search value can be turned into a new option, shown as an extra row at the end of the list. Requires `isSearchable`. |
+| `isDisabled` | `boolean` |  | `false` | Whether the combobox is disabled. |
+| `isFluid` | `boolean` |  | `false` | Whether the combobox fills the available width. |
+| `isLoading` | `boolean` |  | `false` | Whether the panel is waiting for options. Replaces the empty message while there are no options. |
+| `isMulti` | `boolean` |  | `false` | Whether multiple options can be selected. |
+| `isOpen` | `boolean` |  |  | Whether the panel is controlled open. |
+| `isPortaled` | `boolean` |  |  | Whether the panel is wrapped in a floating portal. Defaults to true outside a dialog. |
+| `isRequired` | `boolean` |  | `false` | Whether a selection is required. Sets `aria-required` and, when `name` is provided, enables native form validation. |
+| `isSearchable` | `boolean` |  | `true` | Whether a search input is rendered inside the panel. On by default; turn it off for a short list (roughly 10 options or fewer) where filtering adds nothing. |
+| `isValidNewOption` | `((searchValue: string, options: TOption[]) => boolean)` |  | `(   searchValue: string,   options: ComboboxOption[], ) =>   searchValue.trim() !== '' &&   !options.some((option) => matchesExactly(option, searchValue))` | Whether the search value can become a new option. Defaults to requiring a non-blank value that does not exactly match an existing option or a currently selected one. |
+| `label` | `string` | ✅ |  | Accessible label for the combobox. Rendered above the control. |
+| `loadingMessage` | `ReactNode` |  | `Loading...` | Text of the loading status. Defaults to `Loading...`. |
+| `maxRows` | `number \| null` |  | `1` | Maximum number of rows the selected tags may wrap into, a single row by default. Tags that do not fit are collapsed into a read-only counter tag, such as `+4`, at the end of the last row. Pass `null` to let the control grow with the selection. |
+| `name` | `string` |  |  | Name used to submit the selected option value through a native form. Above 300 options, only the selection is mirrored to the form, so browser autofill no longer offers the option list. |
+| `onChange` | `((value: TOption \| null) => void) \| ((value: TOption[]) => void)` |  |  | Called when the selected option changes. `null` when the selection is cleared. Called when the selected options change. |
+| `onCreateOption` | `((option: TOption) => void)` |  |  | Called after a created option has been selected, so it can be persisted into `options`. Created options are not added to `options` by the combobox. |
+| `onOpenChange` | `((isOpen: boolean) => void)` |  |  | Called when the panel opens or closes. |
+| `onSearchChange` | `((searchValue: string) => void)` |  |  | Called when the search value changes. |
+| `options` | `TOption[] \| ComboboxOptionGroup<TOption>[]` | ✅ |  | The options to display in the combobox. Either an array of options or an array of option groups. |
+| `placeholder` | `string` |  | `Select...` | Text shown in the trigger while nothing is selected. |
+| `portalTarget` | `HTMLElement \| null` |  |  | Portal target element. Defaults to `document.body`. |
+| `ref` | `Ref<HTMLDivElement>` |  |  | A ref to apply to the root element. |
+| `renderTrigger` | `((triggerProps: ComboboxTriggerProps, state: ComboboxTriggerState<TOption>) => ReactNode)` |  |  | Replaces the built-in trigger. Spread `triggerProps` onto the focusable element that should open the panel; the panel is anchored to it. The root element then lays out as `display: contents`, so the trigger is placed by whatever contains the combobox, and `isFluid`, `isClean`, `size`, `className` and `style` no longer shape it. |
+| `searchPlaceholder` | `string` |  | `Search` | Placeholder for the search input, which also names it. |
+| `searchValue` | `string` |  |  | The search value in controlled mode. |
+| `size` | `'large' \| 'medium' \| 'small'` |  | `medium` | Size of the combobox control. |
+| `triggerRef` | `Ref<HTMLElement>` |  |  | Ref to the focusable combobox trigger. |
+| `value` | `ComboboxOption \| TOption[] \| null` |  |  | The selected option in controlled mode. The selected options in controlled mode. |
+
+## Accessibility
+
+## Two compositions
+
+`isSearchable` decides which WAI-ARIA combobox pattern applies. The two must not be mixed.
+
+**Searchable** (the default) — the trigger opens a dialog that contains its own combobox. DOM focus moves to the search input, so the trigger must not carry `aria-activedescendant`.
+
+| Element      | Roles and attributes                                                                                                                |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Trigger      | `role="combobox"`, `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls` pointing at the panel                                 |
+| Panel        | `role="dialog"`, `aria-label` from `label`                                                                                          |
+| Search input | `role="combobox"`, `aria-haspopup="listbox"`, `aria-autocomplete="list"`, `aria-expanded`, `aria-controls`, `aria-activedescendant` |
+| Listbox      | `role="listbox"`, `aria-label` from `label`                                                                                         |
+
+**Not searchable** (`isSearchable={false}`) — the select-only combobox. The trigger is the only `role="combobox"`, DOM focus stays on it while the panel is open, and it owns `aria-activedescendant`.
+
+| Element | Roles and attributes                                                                                    |
+| ------- | ------------------------------------------------------------------------------------------------------- |
+| Trigger | `role="combobox"`, `aria-haspopup="listbox"`, `aria-expanded`, `aria-controls`, `aria-activedescendant` |
+| Panel   | Plain container, no role                                                                                |
+| Listbox | `role="listbox"`, `aria-label` from `label`                                                             |
+
+Nesting a second `role="combobox"` inside the popup is deliberate. The trigger is the form control and owns the field label, the current value, and validation ARIA such as `aria-invalid` and `aria-describedby`; the search input is only a filter control and never carries any of those.
+
+## Naming
+
+`label` is required and is the only accessible name in the API. It names the trigger, the listbox, and the dialog panel, so there is nothing to keep in sync. The separate `name` prop identifies a value during native form submission and does not participate in accessible naming.
+
+Clicking the rendered label moves focus to the trigger without opening the panel, matching a native select label.
+
+`hasVisuallyHiddenLabel` clips the label row out of the layout instead of removing it, so the name survives. Use it when something else already names the control, such as a toolbar heading or a preceding sentence, and never as a way to skip the label.
+
+The search input inside the panel is named by `searchPlaceholder`. A placeholder alone is not a valid accessible name, so the same text is also rendered as a visually hidden label of the input.
+
+## Validation and messages
+
+The trigger is the form control, so it carries all of the validation ARIA.
+
+| Prop         | Effect on the trigger                                                   |
+| ------------ | ----------------------------------------------------------------------- |
+| `helpText`   | `aria-describedby` pointing at the help text                            |
+| `errorText`  | `aria-invalid="true"` and `aria-describedby` pointing at the error text |
+| `isRequired` | `aria-required="true"`                                                  |
+
+- An error replaces the help text, so only one message is ever rendered and only that one is described. Do not put the error in `helpText` as well.
+- The message container is a polite live region that is always in the document, so a validation error is announced when it appears.
+- `hasRequiredIndicator` adds Required or Optional at the end of the label row without changing the accessible name; requiredness is exposed through `aria-required` alone.
+- Without `name`, `isRequired` only marks the trigger with `aria-required`; validation belongs to the form around it.
+- With `name`, `isRequired` also enables native constraint validation. If submission is attempted without a selection, the hidden native control prevents submission, moves focus to the visible trigger, and puts the browser validation message in the existing error live region. An explicit `errorText` takes precedence over that message.
+
+## Native forms
+
+Setting `name` opts the combobox into native form behavior through a visually hidden `<select>`. The select is `aria-hidden` because the visible trigger already exposes the label, value, requiredness, and validation state.
+
+- Single selection submits the selected option's `value`, or an empty string when nothing is selected.
+- Multi selection uses a native `multiple` select, so `FormData.getAll(name)` returns one entry per selected option.
+- Selected creatable values are included even before the consumer adds them to `options`.
+- `form` associates the value with a form elsewhere in the document, and `autoComplete` is forwarded for browser autofill.
+- A disabled combobox is omitted from submission, matching native controls.
+- Native or autofill changes update the combobox, while combobox changes dispatch a bubbling native `change` event for form listeners.
+- `form.reset()` restores `defaultValue` and `defaultSearchValue` and closes uncontrolled state. Controlled values remain owned by their props.
+
+## Roles and attributes on the list
+
+- Options have `role="option"` with `aria-selected` and, when applicable, `aria-disabled`. Action rows are the one exception and carry no `aria-selected`, since nothing about them is selectable.
+- Multi-select listboxes set `aria-multiselectable="true"`.
+- Multi-select checkboxes are visual indicators only and are kept out of the accessibility tree, the tab order, and hit testing. Selection is exposed through each option's `aria-selected` state.
+- Option groups use `role="group"` and are named through `aria-labelledby` by their visible group header.
+- The empty state has `role="status"` so filtering down to no matches is announced. Loading uses the same status slot when `isLoading` is set and there are no options yet.
+
+### Large lists
+
+Above roughly a hundred rows the listbox windows its rendering: only the visible slice of rows is in the DOM. Below that threshold nothing changes.
+
+- Every option carries `aria-setsize` and `aria-posinset` while windowed, so screen readers announce the position in the full list even though the DOM only holds a slice.
+- Group nesting cannot survive windowing, so above the threshold group headers render as presentational rows instead of `role="group"` containers. The visual grouping is unchanged; the group name is not part of the options' ARIA while windowed.
+- Keyboard navigation is unchanged. Moving the active option scrolls it into the window first, so `aria-activedescendant` always resolves to a rendered element.
+
+## Structure of the control
+
+The focusable `role="combobox"` button is the control's first Tab stop. Subsequent Tab presses move through each multi-value remove button in value order and then to the clear button. Clicking anywhere else in the control opens the panel.
+
+A disabled combobox keeps its place in the tab order and is marked with `aria-disabled` rather than the native `disabled` attribute, so it stays discoverable to screen reader users. Selected multi-values remain visible as read-only tags, with no remove or clear buttons, and all selection mutation actions are ignored.
+
+### Limiting the rows of a multi selection
+
+The selected tags are kept to a single row by default. Tags that do not fit are collapsed into one read-only counter tag at the end of the last row, shown as `+N`. `maxRows` raises the cap, and `maxRows={null}` removes it so the control grows with the selection.
+
+- Collapsed tags are taken out of the layout, the accessibility tree, and the tab order, so Tab moves through the visible remove buttons only.
+- The counter is not interactive. It is announced as `N more selected` followed by the collapsed labels, and carries the same list as a `title` tooltip for pointer users. With very many collapsed values, both name at most the first twenty labels and summarize the rest as `and N more`.
+- From one thousand collapsed values the visible counter rounds to whole thousands - `+2K` for 1500 - so it keeps a bounded width. The announced count stays exact.
+- Under a row limit, a selection far larger than the limit could ever show only renders the tags that could possibly be visible; everything past them is part of the counter. With `maxRows={null}` every tag renders, so unbounded rows with thousands of selected values is on the consumer.
+- A collapsed value cannot be removed from the control directly; deselect it through the listbox, where every selected option stays reachable, or with the clear button.
+- Removing a visible tag can bring a collapsed one back into view; focus then moves to the next visible remove button rather than being dropped on a collapsed one.
+
+## Keyboard interaction
+
+### Trigger, panel closed
+
+| Key               | Behavior                                                                  |
+| ----------------- | ------------------------------------------------------------------------- |
+| `ArrowDown`       | Opens the panel. When not searchable, also makes the first option active. |
+| `ArrowUp`         | Opens the panel. When not searchable, also makes the last option active.  |
+| `Enter` / `Space` | Opens the panel without making an option active.                          |
+
+Printable-character typeahead on a closed select-only combobox is not implemented.
+
+### Multi-value remove buttons
+
+| Key               | Behavior                                                                                                                       |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `Enter` / `Space` | Removes the value, then focuses the following remove button or returns focus to the combobox when there is no following value. |
+| `ArrowDown`       | Focuses the combobox and opens the panel, activating the first option when the panel does not contain a search.                |
+| `ArrowUp`         | Focuses the combobox and opens the panel, activating the last option when the panel does not contain a search.                 |
+
+### Clear button
+
+| Key               | Behavior                                                                                                        |
+| ----------------- | --------------------------------------------------------------------------------------------------------------- |
+| `Enter` / `Space` | Clears the selection.                                                                                           |
+| `ArrowDown`       | Focuses the combobox and opens the panel, activating the first option when the panel does not contain a search. |
+| `ArrowUp`         | Focuses the combobox and opens the panel, activating the last option when the panel does not contain a search.  |
+
+### Trigger, panel open and not searchable
+
+Focus stays on the trigger, so it drives the list.
+
+| Key            | Behavior                                                                                                            |
+| -------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `ArrowDown`    | Moves virtual focus to the next option, clamping at the end of the list. With no active option, moves to the first. |
+| `ArrowUp`      | Moves virtual focus to the previous option. With no active option, moves to the last.                               |
+| `Home` / `End` | Moves virtual focus to the first / last option.                                                                     |
+| `Enter`        | Selects the active option; a disabled active option is left alone. With no active option, closes the panel.         |
+| `Space`        | Matches `Enter`.                                                                                                    |
+| `Escape`       | Closes the panel without propagating to an enclosing component.                                                     |
+
+### Search input
+
+Focus is inside the panel, so the trigger sees nothing.
+
+| Key            | Behavior                                                                                                                                                                                                            |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ArrowDown`    | Moves virtual focus to the next option, clamping at the end of the list. With no active option, moves to the first.                                                                                                 |
+| `ArrowUp`      | Moves virtual focus to the previous option. With no active option, moves to the last.                                                                                                                               |
+| `Enter`        | Selects the active option, creates from the search value when the create row is active, or runs an active action. Multi-select toggles it. Does nothing while no option is active or the active option is disabled. |
+| `Escape`       | Clears the search value and closes the panel without propagating to an enclosing component.                                                                                                                         |
+| `Home` / `End` | Left to native text-cursor behavior.                                                                                                                                                                                |
+
+Disabled options are included in keyboard navigation but cannot be selected, following the [APG guidance on the focusability of disabled controls](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls), which keeps them discoverable to screen reader users. Each one carries `aria-disabled="true"` so its state is announced when it takes virtual focus.
+
+No option is active until the user navigates or hovers, and filtering the list clears the active option, so typing a query never puts a selection one keystroke away.
+
+## Creating options
+
+`isCreatable` adds one more `role="option"` at the end of the list, so creating uses the same virtual focus, hover, and activation path as every other option. It carries `aria-selected="false"`, and its accessible name is the create text, which by default reads `Create "<search value>"`.
+
+- Creating needs text to build the option from, so `isCreatable` requires `isSearchable` and warns when it is missing.
+- The create row is only reached by an explicit `ArrowDown`, `ArrowUp`, or hover, and never sits under `Enter` by default, so typing alone never puts a create action one keystroke away.
+- When the query matches nothing, the create row is the only entry in the listbox and replaces the `role="status"` empty state.
+- Activating it selects the created option, so it is announced through the trigger like any other value, and the search value resets so the list is usable again.
+
+## Actions
+
+`actions` adds rows at the end of the list, after a divider, that act instead of selecting. The use case is leaving the selection behind: a row like Create project that navigates into a create flow.
+
+An action is a `role="option"` of the listbox, which gives it virtual focus, hover, and `Enter` like any option. It carries no `aria-selected`, so a screen reader never announces it as an unselected choice.
+
+Visually, actions are pinned below the scrolling options so they stay in view however long the list is. In the DOM they sit after the scrollable listbox, which claims them through `aria-owns`; in the accessibility tree they remain the last options of the listbox, so keyboard navigation and `aria-activedescendant` treat them exactly like rows at the end of the list. When no option matches, there is no scrolling listbox and the pinned container itself becomes the listbox the trigger controls.
+
+- Activating an action runs its `onSelect` and closes the panel, which returns focus to the trigger. The selection is left untouched and `onChange` does not fire.
+- Actions are not results, so they are never filtered by the search value. When nothing matches, the `role="status"` empty state is announced above the list rather than replacing it, and the actions stay reachable.
+- Give an action a label that reads as an action, since the label is its accessible name and nothing in the ARIA says it is not one of the choices.
+- A disabled action stays reachable by keyboard navigation but ignores activation and clicks, the same as a disabled option.
+- Dividers around actions — the one separating them from the options and any `hasDivider` one between two actions — are `aria-hidden` decoration, so a screen reader hears only the rows.
+
+## Focus movement
+
+- Opening a searchable combobox moves focus to the search input. Opening a select-only one leaves focus on the trigger.
+- Closing the panel returns focus to the trigger, whichever way it closed: selection, `Escape`, or an outside click.
+- Single select closes on selection. Multi-select stays open so several options can be picked in one pass, matching `Select`.
+
+## Pointer and keyboard virtual focus
+
+Hovering an option makes it the active option, so hover, `aria-activedescendant`, and what `Enter` selects always agree; hovering a disabled option leaves the active option unchanged. Only keyboard and filter changes scroll the active option into view, since scrolling on hover would move the list out from under the cursor.
+
+## Custom triggers
+
+`renderTrigger` receives the full set of trigger props, including `role="combobox"`, the ARIA above, a keyboard handler, and the ref the panel anchors to. Spread all of them onto a single focusable element. Spreading them onto a non-focusable element breaks keyboard access, since nothing else in the composition is tabbable.
+
+A custom trigger replaces the label and the messages as well as the control, which is what makes an alternative field layout possible. Two things follow from that:
+
+- It is named with `aria-label` rather than `aria-labelledby`, since it is free to leave the label unrendered.
+- It still carries the `aria-describedby` of the message that would have been rendered. `state.field` hands over the label, the help text, the error text, and the ids they need, so render the message that `field.hasError` selects with `field.errorTextId` or `field.helpTextId`. Setting `helpText` or `errorText` and rendering neither leaves the trigger described by an element that does not exist.
+
+## Custom value and option rendering
+
+`components` replaces how an option is presented, never how it behaves. Selection, filtering, virtual focus, and the roles and states of the surrounding elements stay with the combobox, so an override can be as plain as a span.
+
+| Override      | Replaces                                           | Rendered                            |
+| ------------- | -------------------------------------------------- | ----------------------------------- |
+| `MultiValue`  | The tag of a selected value, remove button and all | In the control, next to the trigger |
+| `SingleValue` | The value text of a single select                  | Inside the trigger                  |
+| `OptionLabel` | The label of an option                             | Inside the option                   |
+
+- A `MultiValue` without a removal affordance of its own leaves the list and the clear button as the ways to deselect, so the multi-value remove button keyboard table above no longer applies. Do not also drop `isClearable` unless reopening the panel is an acceptable way back.
+- An override that does render a control has to stop the click from reaching the control, which would otherwise open the panel, and has to place focus itself once the value it lived in is gone. `remove` deselects the option and knows nothing about focus.
+- `SingleValue` is rendered inside the trigger, which is what makes its content read as the current value. It must stay non-interactive, and inline: a block element inside a button is invalid.
+- `OptionLabel` replaces the label of the option rather than the option itself. `role="option"`, `aria-selected`, `aria-disabled`, the multi-select checkbox, and the description are all kept, so option state never rests on the custom presentation alone. Color in particular carries nothing on its own.
+- Every override is handed `isDisabled`, so a disabled combobox is presented as disabled rather than looking active.
+
+## Implementation guidelines
+
+- Provide a concise `label`. It names the trigger, the listbox, and the dialog panel.
+- Reach for `hasVisuallyHiddenLabel` rather than dropping the label when the design has no room for it.
+- Do not rely on leading visuals or selection indicators to communicate option state.
+- Keep the label of an option readable as text when overriding `OptionLabel`, since it is the accessible name of the option.
+
+## Examples
+
+### Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Combobox } from '@neo4j-ndl/react';
+
+const Component = () => {
+  let options = [
+    {
+      label: 'Option 1 ',
+      value: 'option-1',
+    },
+    { label: 'Option 2', value: 'option-2' },
+    {
+      label: 'Option 3 has a really, really, really, really, long label',
+      value: 'option-3',
+    },
+    { isDisabled: true, label: 'Option 4', value: 'option-4' },
+  ];
+
+  return (
+    <Combobox label="Products" options={options} defaultValue={options[0]} />
+  );
+};
+
+export default Component;
+```
+
+### Action On Select
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Combobox, IconButton, TextArea } from '@neo4j-ndl/react';
+import { CommandLineIconOutline } from '@neo4j-ndl/react/icons';
+import { useRef, useState } from 'react';
+
+const commands = [
+  {
+    description: 'Return a small sample of nodes',
+    label: 'Match nodes',
+    value: 'MATCH (n) RETURN n LIMIT 25',
+  },
+  {
+    description: 'Show the labels and relationships in the database',
+    label: 'Visualize schema',
+    value: 'CALL db.schema.visualization()',
+  },
+  {
+    description: 'List the indexes available to the current user',
+    label: 'Show indexes',
+    value: 'SHOW INDEXES',
+  },
+];
+
+const Component = () => {
+  const [terminalValue, setTerminalValue] = useState('');
+  const [searchValue, setSearchValue] = useState('');
+  const textAreaRef = useRef<HTMLTextAreaElement>(null);
+  return (
+    <div className="n-flex n-gap-token-2 n-items-center">
+      <TextArea
+        ref={textAreaRef}
+        label="Command input"
+        value={terminalValue}
+        htmlAttributes={{
+          onChange: (event) => setTerminalValue(event.target.value),
+          rows: 5,
+        }}
+        helpText="Use the button below to search for a command."
+      />
+      <Combobox
+        label="Insert command"
+        options={commands}
+        searchPlaceholder="Search commands"
+        searchValue={searchValue}
+        onSearchChange={setSearchValue}
+        // The picker activates an option but never keeps it as its value.
+        // Keeping the controlled value empty avoids a persistent selected state.
+        value={null}
+        onChange={(command) => {
+          if (command === null) {
+            return;
+          }
+
+          setTerminalValue((currentValue) =>
+            currentValue === ''
+              ? command.value
+              : `${currentValue}\n${command.value}`,
+          );
+          setSearchValue('');
+          textAreaRef.current?.focus();
+        }}
+        renderTrigger={({ ref, ...triggerProps }) => (
+          <IconButton
+            ref={ref as React.Ref<HTMLButtonElement>}
+            description="Insert command"
+            htmlAttributes={triggerProps}
+          >
+            <CommandLineIconOutline />
+          </IconButton>
+        )}
+      />
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### Actions
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Combobox } from '@neo4j-ndl/react';
+import { PlusIconOutline } from '@neo4j-ndl/react/icons';
+
+const options = [
+  { label: 'Movie recommendations', value: 'movie-recommendations' },
+  { label: 'Fraud detection', value: 'fraud-detection' },
+  { label: 'Supply chain', value: 'supply-chain' },
+  { label: 'Customer 360', value: 'customer-360' },
+  { label: 'Knowledge graph', value: 'knowledge-graph' },
+  { label: 'Network topology', value: 'network-topology' },
+  { label: 'Identity resolution', value: 'identity-resolution' },
+  { label: 'Master data management', value: 'master-data-management' },
+  { label: 'Social network analysis', value: 'social-network-analysis' },
+  { label: 'Route optimization', value: 'route-optimization' },
+  { label: 'Recommendation engine', value: 'recommendation-engine' },
+  { label: 'Access control', value: 'access-control' },
+  { label: 'Data lineage', value: 'data-lineage' },
+  { label: 'Entity resolution', value: 'entity-resolution' },
+  { label: 'Bill of materials', value: 'bill-of-materials' },
+  { label: 'Impact analysis', value: 'impact-analysis' },
+  { label: 'Anti money laundering', value: 'anti-money-laundering' },
+  { label: 'Dependency mapping', value: 'dependency-mapping' },
+  { label: 'Patient journey', value: 'patient-journey' },
+  { label: 'Content personalization', value: 'content-personalization' },
+  { label: 'Risk assessment', value: 'risk-assessment' },
+  { label: 'Churn prediction', value: 'churn-prediction' },
+  { label: 'Inventory tracking', value: 'inventory-tracking' },
+  { label: 'Semantic search', value: 'semantic-search' },
+  { label: 'Digital twin', value: 'digital-twin' },
+];
+
+const Component = () => {
+  return (
+    <div className="n-flex n-flex-col n-gap-token-4">
+      <Combobox
+        label="Project"
+        placeholder="Select project"
+        searchPlaceholder="Search projects"
+        options={options}
+        // An action never becomes part of the value. It runs, the panel closes,
+        // and the selection is left as it was, which is what makes it usable for
+        // leaving the combobox entirely.
+        actions={[
+          {
+            label: 'All projects',
+            onSelect: () => console.info('all projects'),
+          },
+          {
+            // A divider above the action separates it from the actions before
+            // it. The first action never needs one: it already sits below the
+            // divider that separates actions from options.
+            hasDivider: true,
+            label: 'Create project',
+            leadingVisual: <PlusIconOutline />,
+            // The search value comes along, so an unmatched query can prefill
+            // the flow the action leads to.
+            onSelect: ({ searchValue }) =>
+              console.info('create project with search value', searchValue),
+          },
+        ]}
+        helpText="actions stay pinned below the scrolling options, and are exempt from searching"
+      />
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### Async
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Combobox, Typography } from '@neo4j-ndl/react';
+import { useEffect, useState } from 'react';
+
+const catalog = [
+  { label: 'Neo4j', value: 'neo4j' },
+  { label: 'Aura', value: 'aura' },
+  { label: 'Bloom', value: 'bloom' },
+  { label: 'Browser', value: 'browser' },
+  { label: 'Cypher', value: 'cypher' },
+  { label: 'Data Importer', value: 'data-importer' },
+  { label: 'GraphQL', value: 'graphql' },
+];
+
+const SEARCH_DELAY_MS = 600;
+
+const Component = () => {
+  const [searchValue, setSearchValue] = useState('');
+  const [options, setOptions] = useState<typeof catalog>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [hasOpened, setHasOpened] = useState(false);
+
+  useEffect(() => {
+    if (!hasOpened) {
+      return;
+    }
+
+    let isCancelled = false;
+    const query = searchValue.trim().toLowerCase();
+
+    setIsLoading(true);
+    setOptions([]);
+
+    const timeoutId = window.setTimeout(() => {
+      if (isCancelled) {
+        return;
+      }
+
+      setOptions(
+        query === ''
+          ? catalog
+          : catalog.filter((option) =>
+              option.label.toLowerCase().includes(query),
+            ),
+      );
+      setIsLoading(false);
+    }, SEARCH_DELAY_MS);
+
+    return () => {
+      isCancelled = true;
+      window.clearTimeout(timeoutId);
+    };
+  }, [hasOpened, searchValue]);
+
+  return (
+    <div className="n-flex n-flex-col n-gap-token-4">
+      <Combobox
+        label="Products"
+        // The consumer supplies already-filtered options, so internal
+        // filtering must be disabled.
+        filterOption={false}
+        searchValue={searchValue}
+        onSearchChange={setSearchValue}
+        onOpenChange={(isOpen) => {
+          if (isOpen) {
+            setIsLoading(true);
+            setHasOpened(true);
+          }
+        }}
+        options={options}
+        isLoading={isLoading}
+        searchPlaceholder="Search products"
+      />
+      <Typography variant="body-small" className="n-text-neutral-text-weak">
+        The consumer clears, fetches, and filters options after a short delay.
+        The loading state is shown while each request is in flight.
+      </Typography>
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### Clean
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Combobox } from '@neo4j-ndl/react';
+
+const Component = () => {
+  const options = [
+    { label: 'Neo4j', value: 'neo4j' },
+    { label: 'Aura', value: 'aura' },
+    { label: 'Bloom', value: 'bloom' },
+    { isDisabled: true, label: 'Unavailable', value: 'unavailable' },
+  ];
+
+  return (
+    <Combobox
+      label="Product"
+      // A clean combobox sits inline, next to whatever already names it.
+      hasVisuallyHiddenLabel
+      isClean
+      options={options}
+      defaultValue={options[0]}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Creatable
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Combobox } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+type Option = {
+  label: string;
+  value: string;
+};
+
+const INITIAL_OPTIONS: Option[] = [
+  { label: 'Recommendations', value: 'recommendations' },
+  { label: 'Fraud detection', value: 'fraud-detection' },
+  { label: 'Knowledge graph', value: 'knowledge-graph' },
+];
+
+const Component = () => {
+  const [options, setOptions] = useState(INITIAL_OPTIONS);
+  const [value, setValue] = useState<Option[]>([]);
+
+  return (
+    <Combobox
+      label="Use cases"
+      placeholder="Select use cases"
+      searchPlaceholder="Search or add a use case"
+      isMulti
+      isCreatable
+      isClearable
+      options={options}
+      value={value}
+      onChange={(nextValue) => setValue(nextValue)}
+      // Created options are not added to `options` by the Combobox, so they are
+      // appended here to keep them available for later selections.
+      onCreateOption={(option) => setOptions((current) => [...current, option])}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Custom Multi
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { tokens } from '@neo4j-ndl/base';
+import { Combobox, GraphLabel } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+// The option type is free to carry fields of its own. Passing these options to
+// the combobox is what types `option` inside the overrides below.
+type NodeLabelOption = {
+  label: string;
+  value: string;
+  color: string;
+};
+
+const options: NodeLabelOption[] = [
+  { color: tokens.graph['1'], label: 'Person', value: 'person' },
+  { color: tokens.graph['2'], label: 'Movie', value: 'movie' },
+  { color: tokens.graph['3'], label: 'Director', value: 'director' },
+  { color: tokens.graph['4'], label: 'Actor', value: 'actor' },
+  { color: tokens.graph['7'], label: 'Genre', value: 'genre' },
+  { color: tokens.graph['12'], label: 'Studio', value: 'studio' },
+];
+
+// One presentation for the selected values and for the options, so both read
+// the same. `as="span"` keeps it non-interactive, which leaves the list and the
+// clear button as the ways to deselect.
+const NodeLabel = ({
+  option,
+  isDisabled,
+}: {
+  option: NodeLabelOption;
+  isDisabled: boolean;
+}) => (
+  <GraphLabel
+    as="span"
+    type="node"
+    size="small"
+    color={option.color}
+    isDisabled={isDisabled}
+  >
+    {option.label}
+  </GraphLabel>
+);
+
+const Component = () => {
+  const [value, setValue] = useState<NodeLabelOption[]>(options.slice(0, 2));
+
+  return (
+    <Combobox
+      label="Node labels"
+      helpText="Deselect a label in the list to remove it."
+      isMulti
+      isClearable
+      options={options}
+      value={value}
+      onChange={setValue}
+      components={{ MultiValue: NodeLabel, OptionLabel: NodeLabel }}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Custom Single
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { tokens } from '@neo4j-ndl/base';
+import { Combobox, GraphLabel } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+// The option type is free to carry fields of its own. Passing these options to
+// the combobox is what types `option` inside the overrides below.
+type NodeLabelOption = {
+  label: string;
+  value: string;
+  color: string;
+};
+
+const options: NodeLabelOption[] = [
+  { color: tokens.graph['1'], label: 'Person', value: 'person' },
+  { color: tokens.graph['2'], label: 'Movie', value: 'movie' },
+  { color: tokens.graph['3'], label: 'Director', value: 'director' },
+  { color: tokens.graph['4'], label: 'Actor', value: 'actor' },
+  { color: tokens.graph['7'], label: 'Genre', value: 'genre' },
+  { color: tokens.graph['12'], label: 'Studio', value: 'studio' },
+];
+
+// One presentation for the selected value and for the options, so both read
+// the same. `as="span"` keeps the label non-interactive.
+const NodeLabel = ({
+  option,
+  isDisabled,
+}: {
+  option: NodeLabelOption;
+  isDisabled: boolean;
+}) => (
+  <GraphLabel
+    as="span"
+    type="node"
+    size="small"
+    color={option.color}
+    isDisabled={isDisabled}
+  >
+    {option.label}
+  </GraphLabel>
+);
+
+const Component = () => {
+  const [value, setValue] = useState<NodeLabelOption | null>(options[0]);
+
+  return (
+    <Combobox
+      label="Node label"
+      isClearable
+      options={options}
+      value={value}
+      onChange={setValue}
+      components={{ OptionLabel: NodeLabel, SingleValue: NodeLabel }}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Custom Trigger
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Combobox, OutlinedButton } from '@neo4j-ndl/react';
+import { AdjustmentsHorizontalIconOutline } from '@neo4j-ndl/react/icons';
+
+const Component = () => {
+  const options = [
+    { label: 'Neo4j', value: 'neo4j' },
+    { label: 'Aura', value: 'aura' },
+    { label: 'Bloom', value: 'bloom' },
+  ];
+
+  return (
+    <Combobox
+      // The custom trigger renders no label of its own, so the label reaches it
+      // as its accessible name only.
+      label="Product"
+      options={options}
+      searchPlaceholder="Search products"
+      // The panel anchors to whichever element the props land on, and that
+      // element becomes the combobox, so it has to be focusable.
+      renderTrigger={({ ref, ...triggerProps }, state) => (
+        <OutlinedButton
+          ref={ref as React.Ref<HTMLButtonElement>}
+          htmlAttributes={triggerProps}
+          leadingVisual={<AdjustmentsHorizontalIconOutline />}
+        >
+          {state.selectedOptions[0]?.label ?? 'Pick a product'}
+        </OutlinedButton>
+      )}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Descriptions
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Combobox } from '@neo4j-ndl/react';
+
+const options = [
+  {
+    description: 'A fully managed graph database service',
+    label: 'AuraDB',
+    value: 'auradb',
+  },
+  {
+    description: 'Graph analytics and data science tools',
+    label: 'Graph Data Science',
+    value: 'graph-data-science',
+  },
+  {
+    description: 'Explore and visualize connected data',
+    label: 'Neo4j Bloom',
+    value: 'neo4j-bloom',
+  },
+];
+
+const Component = () => (
+  <Combobox label="Products" options={options} placeholder="Select product" />
+);
+
+export default Component;
+```
+
+### Disabled
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Combobox } from '@neo4j-ndl/react';
+
+const options = [
+  { label: 'Neo4j', value: 'neo4j' },
+  { label: 'Aura', value: 'aura' },
+  { label: 'Bloom', value: 'bloom' },
+  { label: 'Data Importer', value: 'data-importer' },
+];
+
+const Component = () => (
+  <div className="n-flex n-flex-col n-items-start n-gap-token-16">
+    <Combobox
+      label="Disabled single select"
+      defaultValue={options[0]}
+      isDisabled
+      options={options}
+    />
+    <Combobox
+      label="Disabled multi select"
+      defaultValue={options.slice(0, 3)}
+      isDisabled
+      isMulti
+      options={options}
+    />
+  </div>
+);
+
+export default Component;
+```
+
+### Fluid
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Combobox } from '@neo4j-ndl/react';
+
+const options = [
+  { label: 'Neo4j', value: 'neo4j' },
+  { label: 'Aura', value: 'aura' },
+  { label: 'Bloom', value: 'bloom' },
+  { label: 'Data Importer', value: 'data-importer' },
+];
+
+const Component = () => (
+  <div className="n-w-full">
+    <Combobox
+      label="Product"
+      helpText="This combobox fills the width of its parent."
+      isClearable
+      isFluid
+      options={options}
+    />
+  </div>
+);
+
+export default Component;
+```
+
+### Groups
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Combobox } from '@neo4j-ndl/react';
+
+const Component = () => {
+  let options = [
+    {
+      label: 'Group 1',
+      options: [
+        { label: 'Option 1', value: 'option-1' },
+        { label: 'Option 2', value: 'option-2' },
+        { label: 'Option 3', value: 'option-3' },
+      ],
+    },
+    {
+      label: 'Group 2',
+      options: [
+        { label: 'Option 4', value: 'option-4' },
+        { isDisabled: true, label: 'Option 5', value: 'option-5' },
+        { label: 'Option 6', value: 'option-6' },
+        { label: 'Option 7', value: 'option-7' },
+      ],
+    },
+  ];
+
+  return <Combobox label="Products by category" options={options} />;
+};
+
+export default Component;
+```
+
+### Hidden Label
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Combobox, Typography } from '@neo4j-ndl/react';
+
+const options = [
+  { label: 'Neo4j', value: 'neo4j' },
+  { label: 'Aura', value: 'aura' },
+  { label: 'Bloom', value: 'bloom' },
+];
+
+const Component = () => (
+  <div className="n-flex n-flex-col n-gap-token-4">
+    <Typography variant="body-medium">Filter results by product</Typography>
+    <Combobox
+      label="Product"
+      hasVisuallyHiddenLabel
+      options={options}
+      placeholder="All products"
+    />
+  </div>
+);
+
+export default Component;
+```
+
+### Icons
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Combobox } from '@neo4j-ndl/react';
+import {
+  BeakerIconOutline,
+  BoltIconOutline,
+  CloudIconOutline,
+} from '@neo4j-ndl/react/icons';
+
+const options = [
+  {
+    label: 'AuraDB',
+    leadingVisual: <CloudIconOutline />,
+    value: 'auradb',
+  },
+  {
+    label: 'Graph Data Science',
+    leadingVisual: <BeakerIconOutline />,
+    value: 'graph-data-science',
+  },
+  {
+    label: 'Neo4j Bloom',
+    leadingVisual: <BoltIconOutline />,
+    value: 'neo4j-bloom',
+  },
+];
+
+const Component = () => (
+  <Combobox label="Products" options={options} placeholder="Select product" />
+);
+
+export default Component;
+```
+
+### In Dialog
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Combobox, Dialog, FilledButton } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const options = [
+  { label: 'Neo4j', value: 'neo4j' },
+  { label: 'Aura', value: 'aura' },
+  { label: 'Bloom', value: 'bloom' },
+  { label: 'Data Importer', value: 'data-importer' },
+  { label: 'GraphQL Library', value: 'graphql-library' },
+  { label: 'Cypher', value: 'cypher' },
+];
+
+const Component = () => {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <FilledButton onClick={() => setIsOpen(true)}>Open dialog</FilledButton>
+      <Dialog isOpen={isOpen} onClose={() => setIsOpen(false)} size="medium">
+        <Dialog.Header>Combobox in a dialog</Dialog.Header>
+        <Dialog.Description>
+          The panel automatically uses fixed positioning and stays inside the
+          dialog rather than being portaled.
+        </Dialog.Description>
+        <Dialog.Content>
+          <Combobox
+            label="Product"
+            helpText="Open the list to inspect clipping and stacking."
+            isFluid
+            options={options}
+            searchPlaceholder="Search products"
+          />
+        </Dialog.Content>
+      </Dialog>
+    </>
+  );
+};
+
+export default Component;
+```
+
+### In Popover
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Combobox, FilledButton, Popover, Typography } from '@neo4j-ndl/react';
+
+const options = [
+  { label: 'Neo4j', value: 'neo4j' },
+  { label: 'Aura', value: 'aura' },
+  { label: 'Bloom', value: 'bloom' },
+  { label: 'Data Importer', value: 'data-importer' },
+  { label: 'GraphQL Library', value: 'graphql-library' },
+  { label: 'Cypher', value: 'cypher' },
+];
+
+const Component = () => (
+  <Popover isPortaled>
+    <Popover.Trigger hasButtonWrapper>
+      <FilledButton>Open popover</FilledButton>
+    </Popover.Trigger>
+    <Popover.Content className="n-max-h-[240px] n-w-[400px] n-overflow-y-auto n-p-token-16">
+      <div className="n-flex n-flex-col n-gap-token-16">
+        <Typography variant="body-medium">
+          Scroll this popover while the combobox panel is open to verify that it
+          remains anchored and is not clipped by the overflow container.
+        </Typography>
+        <div className="n-h-[120px] n-shrink-0 n-rounded-sm n-border n-border-neutral-border-strong n-bg-neutral-bg-weak" />
+        <Combobox
+          label="Product"
+          helpText="The combobox panel is independently portaled above this popover."
+          isFluid
+          options={options}
+          searchPlaceholder="Search products"
+        />
+        <div className="n-h-[120px] n-shrink-0 n-rounded-sm n-border n-border-neutral-border-strong n-bg-neutral-bg-weak" />
+      </div>
+    </Popover.Content>
+  </Popover>
+);
+
+export default Component;
+```
+
+### In Popover Dialog
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Combobox, Dialog, FilledButton, Popover } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const options = [
+  { label: 'Neo4j', value: 'neo4j' },
+  { label: 'Aura', value: 'aura' },
+  { label: 'Bloom', value: 'bloom' },
+  { label: 'Data Importer', value: 'data-importer' },
+  { label: 'GraphQL Library', value: 'graphql-library' },
+  { label: 'Cypher', value: 'cypher' },
+];
+
+const Component = () => {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <FilledButton onClick={() => setIsOpen(true)}>Open dialog</FilledButton>
+      <Dialog isOpen={isOpen} onClose={() => setIsOpen(false)} size="medium">
+        <Dialog.Header>Combobox in a popover in a dialog</Dialog.Header>
+        <Dialog.Description>
+          This exercises nested portals, fixed positioning, focus handling, and
+          stacking across all three components.
+        </Dialog.Description>
+        <Dialog.Content>
+          <Popover isPortaled hasAnchorPortal strategy="fixed">
+            <Popover.Trigger hasButtonWrapper>
+              <FilledButton>Open popover</FilledButton>
+            </Popover.Trigger>
+            <Popover.Content className="n-w-[400px] n-p-token-16">
+              <Combobox
+                label="Product"
+                errorText="This error styling should inherit the dialog theme."
+                isFluid
+                options={options}
+                searchPlaceholder="Search products"
+              />
+            </Popover.Content>
+          </Popover>
+        </Dialog.Content>
+      </Dialog>
+    </>
+  );
+};
+
+export default Component;
+```
+
+### Large Data Set
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Combobox } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+type Option = {
+  label: string;
+  value: string;
+};
+
+const options: Option[] = Array.from({ length: 10000 }, (_, index) => ({
+  label: `Node ${index + 1}`,
+  value: `node-${index + 1}`,
+}));
+
+const Component = () => {
+  const [value, setValue] = useState(options.slice(0, 1500));
+
+  return (
+    <Combobox
+      label="Nodes"
+      isClearable
+      isMulti
+      options={options}
+      value={value}
+      onChange={(nextValue) => setValue(nextValue)}
+      helpText="10,000 options with 1,500 selected: the list renders only its visible rows and the counter rounds to thousands."
+    />
+  );
+};
+
+export default Component;
+```
+
+### Max Rows
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Combobox } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+type Option = {
+  label: string;
+  value: string;
+};
+
+const Component = () => {
+  const options: Option[] = [
+    { label: 'Neo4j', value: 'neo4j' },
+    { label: 'Aura', value: 'aura' },
+    { label: 'Bloom', value: 'bloom' },
+    { label: 'Data Importer', value: 'data-importer' },
+    { label: 'GraphQL Library', value: 'graphql-library' },
+    { label: 'Cypher', value: 'cypher' },
+    { label: 'Operations Manager', value: 'operations-manager' },
+    { label: 'Graph Data Science', value: 'graph-data-science' },
+  ];
+  const [value, setValue] = useState(options);
+
+  return (
+    <Combobox
+      label="Products"
+      isClearable
+      isMulti
+      maxRows={2}
+      options={options}
+      value={value}
+      onChange={(nextValue) => setValue(nextValue)}
+      helpText="Set maxRows to 2 to limit the number of rows to 2."
+    />
+  );
+};
+
+export default Component;
+```
+
+### Multi
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Combobox } from '@neo4j-ndl/react';
+import { type ReactNode, useState } from 'react';
+
+type Option = {
+  label: string;
+  value: string;
+  leadingVisual?: ReactNode;
+  description?: string;
+  isDisabled?: boolean;
+};
+
+const Component = () => {
+  const options: Option[] = [
+    { label: 'Neo4j', value: 'neo4j' },
+    { label: 'Aura', value: 'aura' },
+    { label: 'Bloom', value: 'bloom' },
+    { label: 'Data Importer', value: 'data-importer' },
+    {
+      label: 'GraphQL Library has a really really long label',
+      value: 'graphql-library',
+    },
+    { label: 'Cypher', value: 'cypher' },
+    { isDisabled: true, label: 'Unavailable', value: 'unavailable' },
+    { label: 'Operations Manager', value: 'operations-manager' },
+  ];
+  const [value, setValue] = useState(options.slice(0, 5));
+
+  return (
+    <Combobox
+      label="Products"
+      isClearable
+      isMulti
+      options={options}
+      value={value}
+      onChange={(nextValue) => setValue(nextValue)}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Native Form
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import {
+  Combobox,
+  FilledButton,
+  OutlinedButton,
+  TextButton,
+  Typography,
+} from '@neo4j-ndl/react';
+import { type FormEvent, useRef, useState } from 'react';
+
+const products = [
+  { label: 'Neo4j', value: 'neo4j' },
+  { label: 'Aura', value: 'aura' },
+  { label: 'Bloom', value: 'bloom' },
+];
+
+const environments = [
+  { label: 'Development', value: 'development' },
+  { label: 'Staging', value: 'staging' },
+  { label: 'Production', value: 'production' },
+];
+
+const Component = () => {
+  const triggerRef = useRef<HTMLElement | null>(null);
+  const [submittedValues, setSubmittedValues] = useState<string[]>([]);
+
+  const handleSubmit = (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setSubmittedValues(
+      Array.from(new FormData(event.currentTarget).entries()).map(
+        ([name, value]) => `${name}: ${String(value)}`,
+      ),
+    );
+  };
+
+  return (
+    <form
+      className="n-flex n-max-w-xl n-flex-col n-gap-token-6"
+      onSubmit={handleSubmit}
+    >
+      <Combobox
+        label="Product"
+        name="product"
+        options={products}
+        defaultValue={products[0]}
+        isRequired
+        hasRequiredIndicator
+        triggerRef={triggerRef}
+      />
+      <Combobox
+        label="Environments"
+        name="environment"
+        options={environments}
+        defaultValue={[environments[0], environments[1]]}
+        isMulti
+      />
+      <div className="n-flex n-flex-wrap n-gap-token-2">
+        <FilledButton type="submit">Submit</FilledButton>
+        <OutlinedButton type="reset">Reset</OutlinedButton>
+        <TextButton type="button" onClick={() => triggerRef.current?.focus()}>
+          Focus product
+        </TextButton>
+      </div>
+      <div aria-live="polite">
+        <Typography variant="body-medium">Submitted form data</Typography>
+        <pre className="n-mt-token-2">
+          {submittedValues.length > 0
+            ? submittedValues.join('\n')
+            : 'Submit the form to inspect its values.'}
+        </pre>
+      </div>
+    </form>
+  );
+};
+
+export default Component;
+```
+
+### Select Only
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Combobox } from '@neo4j-ndl/react';
+
+const Component = () => {
+  const options = [
+    { label: 'Neo4j', value: 'neo4j' },
+    { label: 'Aura', value: 'aura' },
+    { label: 'Bloom', value: 'bloom' },
+    { isDisabled: true, label: 'Cypher', value: 'cypher' },
+  ];
+
+  // A list this short has nothing to filter, so the search input is turned
+  // off and the combobox follows the select-only pattern.
+  return <Combobox label="Products" isSearchable={false} options={options} />;
+};
+
+export default Component;
+```
+
+### Sizes
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Combobox } from '@neo4j-ndl/react';
+
+const options = [
+  { label: 'Neo4j', value: 'neo4j' },
+  { label: 'Aura', value: 'aura' },
+  { label: 'Bloom', value: 'bloom' },
+];
+
+const Component = () => (
+  <div className="n-flex n-flex-col n-gap-token-16">
+    {(['small', 'medium', 'large'] as const).map((size) => (
+      <div className="n-flex n-flex-col n-gap-token-4" key={size}>
+        <p className="n-capitalize">{size}</p>
+        <div className="n-flex n-flex-wrap n-items-start n-gap-token-16">
+          <Combobox
+            label={`${size} single-select`}
+            defaultValue={options[0]}
+            options={options}
+            size={size}
+          />
+          <Combobox
+            label={`${size} multi-select`}
+            defaultValue={options.slice(0, 2)}
+            isMulti
+            options={options}
+            size={size}
+          />
+        </div>
+      </div>
+    ))}
+  </div>
+);
+
+export default Component;
+```
+
+### Unlimited Rows
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Combobox } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+type Option = {
+  label: string;
+  value: string;
+};
+
+const Component = () => {
+  const options: Option[] = [
+    { label: 'Neo4j', value: 'neo4j' },
+    { label: 'Aura', value: 'aura' },
+    { label: 'Bloom', value: 'bloom' },
+    { label: 'Data Importer', value: 'data-importer' },
+    { label: 'GraphQL Library', value: 'graphql-library' },
+    { label: 'Cypher', value: 'cypher' },
+    { label: 'Operations Manager', value: 'operations-manager' },
+    { label: 'Graph Data Science', value: 'graph-data-science' },
+  ];
+  const [value, setValue] = useState(options);
+
+  return (
+    <Combobox
+      label="Products"
+      isClearable
+      isMulti
+      maxRows={null}
+      options={options}
+      value={value}
+      onChange={(nextValue) => setValue(nextValue)}
+      helpText="Set maxRows to null to let the control grow with the selection."
+    />
+  );
+};
+
+export default Component;
+```
+
+### Validation
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { Combobox } from '@neo4j-ndl/react';
+
+const options = [
+  { label: 'Neo4j', value: 'neo4j' },
+  { label: 'Aura', value: 'aura' },
+  { label: 'Bloom', value: 'bloom' },
+];
+
+const Component = () => (
+  <div className="n-flex n-flex-col n-gap-token-16">
+    <Combobox
+      label="Product"
+      helpText="Pick the product the ticket is about."
+      isRequired
+      hasRequiredIndicator
+      options={options}
+    />
+    <Combobox
+      label="Product"
+      errorText="Select a product to continue."
+      isRequired
+      hasRequiredIndicator
+      options={options}
+    />
+    <Combobox
+      label="Environment"
+      helpText="Leave empty to include every environment."
+      hasRequiredIndicator
+      options={options}
+    />
+  </div>
+);
+
+export default Component;
+```