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

<mth-site-search>

@methane-ui/ui~12.3 KB brotli (cold + Lit)~4.4 KB marginal

Async site search combobox backed by DataController, ListboxController, positioned [popover] results overlay, and optional keyboard focus shortcut.

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

Live Interactive Preview

Multi-Framework Playground & Snippets

<script type="module" src="@methane-ui/ui/site-search"></script>
<mth-site-search shortcut="/"></mth-site-search>

Properties & Attributes

PropertyAttributeTypeDefaultDescription
openopenbooleanfalseControls visibility of the search results popup.
queryquerystring""Current search query string.
labellabelstring""Accessible label override for the search input.
placeholderplaceholderstring""Placeholder override for the search input.
shortcutshortcutstring"/"Global hotkey that focuses the search input when not inside an editable control.
registerShortcutregister-shortcutbooleanfalseEnables the document focus shortcut listener.
forceFallbackforce-fallbackbooleanfalseForces JS fallback overlay/positioning instead of native [popover].
items—ReadonlyArray<unknown>[]Local fallback items searched when no external dataSource is provided.

Events

EventDetail TypeDescription
mth-openvoidCancelable event dispatched before the search results popup opens.
mth-closevoidCancelable event dispatched before the search results popup closes.
mth-query-change{ query: string }Dispatched when the user edits the search query.
mth-select{ id: string; label: string; href?: string }Dispatched when a search result option is selected.

APG Keyboard Matrix

KeyDirectionWhenExpected Behavior
ArrowDownbothinput focusedopens results and activates next result
ArrowUpbothinput focusedactivates previous result
Enterbothresult activeemits mth-select and closes popup
Escapebothpopup opencloses popup

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 4 APG keyboard transitions across LTR/RTL.mth-site-search.spec.test.ts
statesExposes ElementInternals CustomStateSet flags: :state(open), :state(loading), :state(empty), :state(error).Conformance suite
i18nRoutes 7 UI/ARIA strings through @methane-ui/core i18n catalog.Locale context test