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

<mth-cascader>

@methane-ui/ui~11.2 KB brotli (cold + Lit)~3.8 KB marginal

Hierarchical multi-column cascader picker with form association, keyboard drill-down, and popover overlay.

When NOT to use: Use a lightweight @methane-ui/css layout class instead of a custom element when static CSS suffices.

Live Interactive Preview

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

Multi-Framework Playground & Snippets

<script type="module" src="@methane-ui/ui/cascader"></script>
<mth-cascader separator="/" clearable></mth-cascader>

Properties & Attributes

PropertyAttributeTypeDefaultDescription
namenamestring""Form field name submitted with FormData.
valuevaluestring""Selected path serialized with separator.
defaultValuedefault-valuestring""Initial path value used when resetting the form.
separatorseparatorstring"/"Delimiter used between path segments in value and display.
options—ReadonlyArray<unknown> | nullnullHierarchical tree of CascaderOption items.
labellabelstring""Accessible field label.
placeholderplaceholderstring""Placeholder shown when no path is selected.
hinthintstring""Helper text displayed below the control.
errorerrorstring""Explicit error text displayed below the control.
openopenbooleanfalseControls whether the cascading popup is open.
disableddisabledbooleanfalseDisables user interaction and form submission.
requiredrequiredbooleanfalseMarks selection as required for form validation.
clearableclearablebooleantrueShows a clear button when a value is selected.
changeOnSelectchange-on-selectbooleanfalseCommits intermediate parent nodes immediately on click.
expandTriggerexpand-trigger'click' | 'hover'"click"Interaction that opens child columns (click or hover).

Events

EventDetail TypeDescription
mth-change{ value: string; path: ReadonlyArray<string>; selectedOptions: ReadonlyArray<unknown> }Fired when the selected path changes or is cleared.
mth-openundefinedCancelable event fired before opening the popup.
mth-after-openundefinedFired after the popup opens.
mth-closeundefinedCancelable event fired before closing the popup.
mth-after-closeundefinedFired after the popup closes.

APG Keyboard Matrix

KeyDirectionWhenExpected Behavior
Enter / Space / ArrowDownbothtrigger focused and closedopens cascader popup
ArrowDown / ArrowUpbothpopup openmoves focus within active column
ArrowRight / ArrowLeftbothpopup opendrills into child column or returns to parent column (RTL-aware)
Enterbothoption focusedexpands children or commits leaf selection
Escapebothpopup opencloses popup and restores focus to trigger

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-cascader.spec.test.ts
statesExposes ElementInternals CustomStateSet flags: :state(dirty), :state(touched), :state(user-invalid), :state(disabled), :state(required).Conformance suite
i18nRoutes 5 UI/ARIA strings through @methane-ui/core i18n catalog.Locale context test