Methane@methane-ui/*
CSS LayoutsComponentsSkillsTheme BuilderGitHub
← All Components

<mth-combobox>

@methane-ui/ui~15.6 KB brotli (cold + Lit)~6.2 KB marginal

Form-associated accessible combobox reconciling declarative <mth-option>/<mth-option-group>, .options JS arrays, and async DataSource<T> queries with same-root shadow ARIA and dual CSS Anchor / JS positioning.

When NOT to use: Do not use <mth-combobox> for 2–4 static choices without search; use <mth-radio-group> or native <select>.

Live Interactive Preview

Interactive StageLive Custom Element · <mth-combobox> (@methane-ui/ui)
Ready · interact with <mth-combobox>, or toggle Theme, Direction (LTR/RTL), or props above.

Multi-Framework Playground & Snippets

<script type="module" src="@methane-ui/ui/combobox"></script>
<mth-combobox filterable placement="bottom-start">Example</mth-combobox>

Properties & Attributes

PropertyAttributeTypeDefaultDescription
namenamestring""Form field name submitted via ElementInternals.
valuevaluestring""Current selected value (comma-separated when multiple is true).
defaultValuedefault-valuestring""Initial value restored when the enclosing form resets.
labellabelstring""Visible and accessible label for the combobox input.
hinthintstring""Helper text describing expected input or options.
errorerrorstring""Explicit error message marking the combobox invalid.
placeholderplaceholderstring""Input placeholder text.
openopenbooleanfalseControls visibility of the floating options popup.
multiplemultiplebooleanfalseEnables multi-value selection without dismissing on selection.
disableddisabledbooleanfalseDisables interaction and excludes from form submission.
requiredrequiredbooleanfalseMarks combobox selection as required for constraint validation.
readonlyreadonlybooleanfalsePrevents typing or changing selection while remaining focusable.
clearableclearablebooleanfalseShows a clear button when text or value is non-empty.
filterablefilterablebooleantrueFilters local options dynamically as the user types.
placementplacementstring"bottom-start"Preferred popup placement relative to the combobox control.
forceFallbackforce-fallbackbooleanfalseForces JS fallback positioning instead of native CSS Anchor Positioning.
options—ReadonlyArray<{ readonly id?: string; readonly value: string; readonly label: string; readonly disabled?: boolean; readonly group?: string }> | nullnullImperative option array overriding declarative slotted children.
dataSource—{ query(request: { cursor?: string; filter?: string; signal: AbortSignal }): Promise<{ items: ReadonlyArray<{ readonly id?: string; readonly value: string; readonly label: string; readonly disabled?: boolean; readonly group?: string }>; total?: number; nextCursor?: string | null }> } | nullnullAsync DataSource<T> queried on filter changes with stale-request abort protection.

Events

EventDetail TypeDescription
mth-input{ value: string }Fired as the user types in the combobox input.
mth-change{ value: string; selectedValues: ReadonlyArray<string> }Fired when selection changes.
mth-openvoidCancelable event fired before opening the popup.
mth-after-openvoidFired after the popup opens and positions.
mth-close{ reason: string }Cancelable event fired before closing the popup.
mth-after-close{ reason: string }Fired after the popup closes.
mth-clearvoidFired when the clear action resets query and selection.
mth-invalid{ validity: ValidityState }Fired when form constraint validation fails.

APG Keyboard Matrix

KeyDirectionWhenExpected Behavior
ArrowDownbothclosedopens popup and activates first enabled option
ArrowDownbothopenmoves active option highlight to next enabled option
ArrowUpbothopenmoves active option highlight to previous enabled option
Enterbothopen and not composing IMEselects active option and updates value
Escapebothopendismisses popup and restores focus

Accessibility Checklist

CategoryRequirementVerified By
ariaAll aria-* IDREFs resolve within the same DOM root (ADR-003).scanSameRootAria
focusdelegatesFocus: true with zero host internals.role (ADR-014).lint-plugin & spec-compiler
contrastRenders legible borders, focus outlines, and selection indicators under forced-colors: active.Playwright forced-colors matrix
keyboardImplements all 5 APG keyboard transitions across LTR/RTL.mth-combobox.spec.test.ts
statesExposes ElementInternals CustomStateSet flags: :state(open), :state(dirty), :state(touched), :state(user-invalid), :state(disabled), :state(readonly), :state(required), :state(invalid), :state(loading), :state(empty), :state(error).Conformance suite
i18nRoutes 6 UI/ARIA strings through @methane-ui/core i18n catalog.Locale context test