@outbook/webcomponents-form-combobox-select

A customizable, accessible combobox select web component built with Lit and Haunted.

Features

• Fully accessible following WAI-ARIA combobox patterns.
• Supports type-ahead searching.
• Keyboard navigation (Arrow keys, Enter, Escape, PageUp/Down, Home/End).
• Integrated validation and error messaging.
• Multi-language support (i18n).
• Easy to use as a standalone custom element or through a Lit-ready wrapper function.

Installation

npm install @outbook/webcomponents-form-combobox-select

Usage

Direct Custom Element

You can use the <outbook-form-combobox-select> tag directly in your HTML. To set the options, you must assign the options property via JavaScript.

<outbook-form-combobox-select
  label="Select an option"
  description="Please choose one from the list"
  input-name="my-selection"
  required="required"
></outbook-form-combobox-select>

<script type="module">
  import '@outbook/webcomponents-form-combobox-select';

  const combobox = document.querySelector('outbook-form-combobox-select');
  combobox.options = [
    { value: '1', label: 'Option One' },
    { value: '2', label: 'Option Two' },
    { value: '3', label: 'Option Three' }
  ];

  combobox.addEventListener('change', e => {
    console.log('Selected value:', e.detail.value);
  });
</script>

Wrapper Helper Function (Lit)

If you are using Lit, you can use the FormComboboxSelect helper function for a more declarative approach.

import { html } from 'lit';
import { FormComboboxSelect } from '@outbook/webcomponents-form-combobox-select';

const myOptions = [
  { value: 'apple', label: 'Apple' },
  { value: 'banana', label: 'Banana' },
  { value: 'cherry', label: 'Cherry' }
];

const template = html`
  ${FormComboboxSelect({
    label: 'Favorite Fruit',
    inputName: 'fruit',
    options: myOptions,
    isRequired: true,
    placeholder: 'Select a fruit...',
    validateFn: e => console.log('Is valid:', e.detail.isValid),
    onChange: e => console.log('Changed to:', e.detail.value)
  })}
`;

API Reference

Attributes & Properties

| Attribute | Property | Type | Default | Description | | :----------------- | :---------------- | :----------------------- | :------------- | :------------------------------------------------------------------------------- | | input-name | inputName | string | - | Name attribute for the underlying hidden input. | | description | description | string | - | Helper text displayed below the field. | | label | label | string | - | Label text for the combobox. | | labelledby | labelledby | string | - | ID of an external element to use as a label (ARIA). | | input-id | inputId | string | auto-generated | ID for the combobox element. | | required | required | 'required'\|'optional' | 'optional' | Whether the field is mandatory. | | disabled | disabled | boolean | false | Disables the component when true. | | validate-message | validateMessage | string | - | Custom error message to show when invalid. | | placeholder | placeholder | string | - | Text to show when no option is selected. | | lang | lang | string | 'en' | Language code for internationalization. | | test-id | testId | string | - | ID for testing purposes (data-test-id). | | - | options | Array | [] | Array of options. Each can be a string or { value, label, content, selected }. |

Events

| Event | Detail | Description | | :------------ | :-------------------------------- | :----------------------------------- | | change | { index, value, label, option } | Fired when an option is selected. | | validated | { isValid } | Fired when validation state changes. | | input-keyup | { originalEvent } | Fired on keyup within the combobox. |

Imperative Methods

• reset(): Resets the selection and validation state.
• getValue(): Returns the currently selected value.

Styling

The component uses Shadow DOM. Customization is primarily handled through the internal SCSS, following the project's design system.