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

<mth-toggle-group>

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

Form-associated single or multi-select toggle button group with roving focus, RTL awareness, and FACE validation.

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-toggle-group> (@methane-ui/ui)
Ready · interact with <mth-toggle-group>, or toggle Theme, Direction (LTR/RTL), or props above.

Multi-Framework Playground & Snippets

<script type="module" src="@methane-ui/ui/toggle-group"></script>
<mth-toggle-group orientation="horizontal" size="sm">Example</mth-toggle-group>

Properties & Attributes

PropertyAttributeTypeDefaultDescription
namenamestring""Form submission field name.
valuevaluestring""Selected value (or comma-separated values when multiple is true).
defaultValuedefault-valuestring""Initial value restored on form reset.
labellabelstring""Accessible label for the toggle group.
hinthintstring""Helper text linked via aria-describedby.
errorerrorstring""Explicit validation error message.
multiplemultiplebooleanfalseAllows toggling multiple pressed items simultaneously.
orientationorientation'horizontal' | 'vertical'"horizontal"Roving focus orientation (horizontal or vertical).
sizesize'sm' | 'md' | 'lg'"md"Visual button size (sm, md, or lg).
disableddisabledbooleanfalseDisables all items in the group.
requiredrequiredbooleanfalseRequires at least one selected item for form submission.
options—ReadonlyArray<unknown> | nullnullImperative array of toggle items.

Events

EventDetail TypeDescription
mth-change{ value: string; values: ReadonlyArray<string> }Fired when toggle selection changes.

APG Keyboard Matrix

KeyDirectionWhenExpected Behavior
ArrowRightltrfocused horizontal groupmoves focus to next item
ArrowLeftrtlfocused horizontal groupmoves focus to next item in RTL
ArrowDownbothfocused vertical groupmoves focus to next item
Homebothfocused on any itemmoves focus to first enabled item
Endbothfocused on any itemmoves focus to last enabled item
Enter / Spacebothfocused on an itemtoggles selection and updates value

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 6 APG keyboard transitions across LTR/RTL.mth-toggle-group.spec.test.ts
statesExposes ElementInternals CustomStateSet flags: :state(dirty), :state(touched), :state(user-invalid), :state(disabled), :state(required).Conformance suite
i18nRoutes 2 UI/ARIA strings through @methane-ui/core i18n catalog.Locale context test