Combobox

Playground

This component's contract doesn't list typed props, so the playground shows its documented example.

Documented example combobox-filter-and-pick : type to filter, then Down and Enter, or click an option, the picked value emitted once and the list closed.

The render follows the page's theme switch: light, dark or high contrast. Both frameworks render the same example.

Code

The documented example. HTML is the markup the React component renders for it, which @oods/component-styles styles.

import { Combobox } from '@oods/components-react';
import '@oods/component-styles/css';

const options = [
  {
    "value": "au",
    "label": "Australia"
  },
  {
    "value": "ca",
    "label": "Canada"
  },
  {
    "value": "fr",
    "label": "France"
  },
  {
    "value": "de",
    "label": "Germany"
  },
  {
    "value": "jp",
    "label": "Japan",
    "disabled": true
  },
  {
    "value": "mx",
    "label": "Mexico"
  },
  {
    "value": "gb",
    "label": "United Kingdom"
  },
  {
    "value": "us",
    "label": "United States"
  }
];

export function Example() {
  return (
    <Combobox
      id="shipping-country"
      label="Shipping country"
      value="ca"
      placeholder="Search countries"
      help="Type to filter. We do not ship to Japan yet."
      options={options}
    />
  );
}

Props, slots and events

Contract version 1.1.0. Types are from the React declarations in @oods/components-react.

Slots

label, help, validation

Events

change, update

States

closed, open, no-matches, selected, disabled, invalid

Accessibility

Role

combobox

How it gets its name

label on input[role="combobox"]

Keyboard

Obligations in the contract

• An input with role combobox controls a listbox popup and reports aria-expanded, aria-autocomplete list and, while an option is active, aria-activedescendant; focus stays in the input
• The visible label names the combobox and its listbox; help and error text describe the input
• The chosen option reports aria-selected and shows a check mark; a disabled option reports aria-disabled and is skipped
• Down opens the list and moves, Up moves, Home and End go to the ends, Enter picks the active option, Escape closes the list and then clears the field, and Tab closes the list without picking

Typing filters the options to those whose label contains the typed text, ignoring case, and opens the list; when none matches the popup says No matches, which is not an option. value (controlled) or defaultValue (uncontrolled) names the chosen option, and the input shows its label. Picking an option (Enter on the active one, or a click) emits change and update with its value and closes the list; Escape with the list closed empties the input and, when an option was chosen, emits them with an empty value. An outside click or Tab closes the list without picking, and leaving the field restores the chosen label. size is the control height: xs 24, sm 28, md 32 (default) or lg 40, as Input, Select and Button. name submits the chosen value through a hidden input. The HTML renderer writes the same markup with the list closed and appends an inline script (data-oods-runtime="combobox") that gives it the same behaviour; without the script the input still shows the chosen label. One value only: no multiple selection, async loading, created values, grouped options or virtualization.

Tokens

The token roles this component reads.

• input.background
• input.border
• input.text
• input.placeholder
• input.focus
• combobox.popup
• combobox.shadow
• combobox.option
• combobox.optionActive
• combobox.check
• field.message

Readiness

The evidence recorded for this component, with its label.

react-and-vue: catalog_list gives this label when the React and Vue components have complete readiness evidence, but the sweep's generated apps don't use the component in both.

Use your own

You can replace this component with your own React or Vue component. Map it, and generated code imports yours at the exact version you name. A contract report, run in a real browser, lists what your component met, what it didn't, and what wasn't checked.

The component_map call, with the parts in angle brackets yours to fill:

{
  "action": "create",
  "apply": true,
  "externalSystem": "<your design system>",
  "externalComponent": "<YourCombobox>",
  "oodsTraits": [
    "<trait names>"
  ],
  "substitution": {
    "component": "Combobox",
    "react": {
      "package": "<your-package>/react",
      "version": "<exact version>",
      "export": "<YourCombobox>"
    },
    "vue": {
      "package": "<your-package>/vue",
      "version": "<exact version>",
      "export": "<YourCombobox>"
    }
  }
}

How this page was made

Generated at build from the published data, each source with the hash of what was read. The page's manifest.

• Contract: @oods/component-contracts@0.10.1 componentContracts.Combobox sha256:5f47a8255353…
• Documented example: @oods/component-contracts@0.10.1 sharedScenarios combobox-filter-and-pick sha256:103a3b387abd…
• Catalog entry (catalog_list): generated/0.10.1/system/catalog.json Combobox sha256:6bbb68a42aad…
• React readiness: @oods/components-react@0.10.1 readiness Combobox sha256:ee0b91102606…
• Vue readiness: @oods/components-vue@0.10.1 readiness Combobox sha256:2421c99eda16…
• Prop types: generated/0.10.1/components/prop-types.json Combobox sha256:baca099af2ae…