Skip to content
Kimenpre-v1documentation home
Color scheme

ki-search

Use Search to accept a query and surface related suggestions, recent searches and results. In auto mode the view docks to the bar at 600 CSS pixels and above. At smaller widths it opens in a full-screen modal.

Theme for this example
Color scheme for this example
Dialog button tokens

Start with the component accessibility guide.

<ki-search label="Search Kimen" placeholder="Search Kimen" name="q">
<ki-search-suggestion value="ki-dialog" description="Component">Dialog</ki-search-suggestion>
<ki-search-suggestion recent>button tokens</ki-search-suggestion>
<p slot="results">Start with the component accessibility guide.</p>
</ki-search>

Queries and results

Listen for ki-input to update suggestions after typing pauses. Set loading while the request runs. Listen for ki-search to run the query and render content in the results slot. Both events expose detail.value. Search stays open after selection. The named field contributes its current query to native forms.

Use ki-clear to clear host results and ki-remove-recent to persist history removals. Supply a labelled button in the trailing slot for voice search.

Keyboard

Focus the field to open Search. Use the arrows to move through suggestions and Enter to run the active suggestion or the typed query. Tab reaches recent queries, their Remove buttons and any interactive results. Escape clears a nonempty query. Escape on an empty query closes the view and restores focus to the bar. The full-screen view also offers a Back button.

API reference

When to use: accept free-text searches and let the user run a typed or suggested query. Listen for ki-input to update suggestions, and ki-search to render results.

When not to use: selecting one value from a fixed set belongs in ki-select. Use ki-input when a plain search field is enough.

Properties & attributes

AttributePropertyTypeDefaultDescription
back-labelbackLabelstring'Back'Accessible name of the full-screen Back button.
clear-labelclearLabelstring'Clear search'Accessible name of the query clear button.
highlighthighlightbooleantrueEmphasize literal, case-insensitive matches in suggestion titles.
labellabelstring'Search'Accessible name of the search landmark, input and full-screen dialog.
loadingloadingbooleanfalseShow a loading indicator while the host fetches suggestions.
loading-labelloadingLabelstring'Loading suggestions'Accessible name of the loading indicator.
modemode"auto" | "docked" | "fullscreen"'auto'View presentation. Auto uses a full-screen dialog below 600 CSS pixels.
namenamestring | undefined–Name under which the current query is included in form data.
openopenbooleanfalseWhether the search view is open. The field opens it on focus, click or input.
placeholderplaceholderstring''Optional hint displayed inside the empty search field.
recent-labelrecentLabelstring'Recent searches'Visible and accessible name of the recent-search group.
remove-recent-labelremoveRecentLabelstring'Remove {value}'Accessible name template for recent-query removal. Use {value} for the query title.
suggestion-count-pluralsuggestionCountPluralstring'{count} suggestions'Polite announcement for zero or multiple suggestions. Use {count} for the number.
suggestion-count-singularsuggestionCountSingularstring'1 suggestion'Polite announcement when the list contains one suggestion.
suggestions-labelsuggestionsLabelstring'Suggestions'Accessible name of the suggestion listbox.
valuevaluestring''Current query. Edits and selected suggestions update this property.

Events

EventDetail typeDescription
ki-clearCustomEvent<void>The user cleared the query with the clear control or with Escape.
ki-inputCustomEvent<KiSearchValueDetail>The current query after 200 ms of inactivity following an edit.
ki-remove-recentCustomEvent<KiSearchValueDetail>The removed recent query. Hosts can use this to persist the updated history.
ki-searchCustomEvent<KiSearchValueDetail>The query to run, emitted on Enter or activation of a suggestion or recent search.

Slots

SlotDescription
(default)Direct ki-search-suggestion children supply suggestion and recent-query data.
leadingA control or decorative icon at the start of the collapsed or docked bar.
resultsHost-rendered results beneath suggestions and recent searches.
trailingA control or avatar at the end of the collapsed or docked bar. Supply a labelled button here to surface voice search.

CSS parts

PartDescription
barCollapsed and docked search bar.
dialog-barSearch bar inside the full-screen view.
inputNative query input in each presentation.
optionA selectable suggestion in the listbox.
recentLabelled group of recent searches.
resultsContainer around host-rendered results.
viewDocked popover or full-screen dialog surface.

CSS custom properties

The public styling contract of ki-search: reassign these tokens at :root or on a subtree — never override internals.

TokenDescription
--ki-density-control-offsetAdded to the block size of every scaled control and row (button, icon button, field, select, textarea, option, list item, tab). Components floor the result at ki.size.target-min.
--ki-density-target-minThe smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1).
--ki-focus-ring-colorColour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme.
--ki-focus-ring-widthThickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once.
--ki-glyph-size-mdMedium glyph for body content (20px at the default root size).
--ki-layout-spacing-3xlThe 3xl spacing step for a stack or grid gap.
--ki-layout-spacing-mdThe md spacing step for a stack or grid gap.
--ki-layout-spacing-smThe sm spacing step for a stack or grid gap.
--ki-layout-spacing-xlThe xl spacing step for a stack or grid gap.
--ki-layout-spacing-xsThe xs spacing step for a stack or grid gap.
--ki-search-bar-backdrop-filterComplete backdrop filter for the bar.
--ki-search-bar-bgFill of the collapsed and docked bar.
--ki-search-bar-bg-imageOptional image painted over the bar fill.
--ki-search-bar-fgQuery ink over the search bar.
--ki-search-bar-heightMinimum height of the search bar, 56px at the default root size.
--ki-search-bar-placeholderPlaceholder ink exposed by the Search API.
--ki-search-bar-placeholder-fgDefault contrast pair for placeholder text over the search bar.
--ki-search-bar-radiusPill corner of the collapsed and docked bar.
--ki-search-control-sizeBase size of actions and minimum height of search rows.
--ki-search-group-heading-familyFont family for the recent-query group heading.
--ki-search-input-touch-sizeMinimum input font size on coarse pointers to avoid focus zoom.
--ki-search-option-active-bgFill of the focused or hovered suggestion.
--ki-search-option-active-fgInk of the focused or hovered suggestion.
--ki-search-option-active-supporting-fgDescription ink on the focused or hovered suggestion.
--ki-search-view-backdrop-filterComplete backdrop filter for the search view.
--ki-search-view-bgRaised fill of the docked and full-screen view.
--ki-search-view-bg-imageOptional image painted over the view fill.
--ki-search-view-dividerDivider separating the active field and full-screen results.
--ki-search-view-fgInk over the search view.
--ki-search-view-radiusCorner for the docked view.
--ki-search-view-shadowResting elevation of the docked view.
--ki-search-view-supporting-fgInk for descriptions and the recent-search group label.
--ki-typography-family-bodysemantic font family for typography family body.
--ki-typography-size-body-1semantic dimension for typography size body 1.
--ki-typography-size-body-2semantic dimension for typography size body 2.
--ki-typography-size-caption-2semantic dimension for typography size caption 2.
--ki-typography-visually-hidden-sizeNonzero edge for clipped text available to assistive technology.
--ki-typography-weight-body-boldsemantic font weight for typography weight body bold.
--ki-typography-weight-body-mediumsemantic font weight for typography weight body medium.

When to use: supply one suggested or recent query as a direct ki-search child.

When not to use: standalone display, form options or arbitrary results content. Use the results slot of ki-search for independently rendered results.

Properties & attributes

AttributePropertyTypeDefaultDescription
descriptiondescriptionstring | undefined–Optional supporting text displayed below the title.
recentrecentbooleanfalseDisplay in the removable recent-search group.
valuevaluestring | undefined–Query to run. When omitted, the trimmed title is used.

Slots

SlotDescription
(default)Plain text title displayed in the owning search view.

CSS custom properties

The public styling contract of ki-search-suggestion: reassign these tokens at :root or on a subtree — never override internals.

TokenDescription
--ki-search-suggestion-font-familyInherited body typeface on the declarative suggestion host.