Search
<esp-search>
Modal search overlay with a Cmd+K / Ctrl+K interaction pattern.
<esp-search> is a pure UI shell with no search-engine dependency.
Consumers wire it to any search backend (Pagefind, MiniSearch, API,
etc.) by listening for search-requested events and calling
setResults() with the matches.
Examples
Basic search (consumer wiring not shown)
Properties
EspalierSearch has the following properties:
placeholder
placeholder has a type of string.
Placeholder text for the search input.
isOpen
Type: boolean
results
Type: SearchResult[]
loading
Type: boolean
query
Type: string
activeIndex
Type: number
vellumRef
—
inputRef
—
resultsRef
—
idPrefix
Per-instance ID prefix for ARIA id attributes (listbox + options).
_overlay
—
hasListbox
hasListbox has a type of boolean.
Whether the listbox is currently rendered in the DOM.
listboxId
Type: string
seedColorBacker
Type: string
espRoot
Type: EspalierRoot | null
variantBacker
Type: EspalierVariant
seedColor
Type: string
correlationId
—
scheme
scheme has a type of "dark" | "light".
The scheme to use for the component. This property is used internally to control the light/dark scheme so it matches the scheme of esp-root. It should not be set manually, it exists as an attribute for styling purposes.
textContrast
textContrast has a type of `Partial<
Record<SemanticColorName, { bg: SemanticColorName; targetLc: number }>
`.
Text tokens that require APCA contrast enforcement.
Each entry maps a text-bearing semantic token to:
bg: the semantic token it sits on (reference color)targetLc: the minimum |Lc| the text must achieve
Events
<esp-search> emits the following events:
search-requested
search-requested is of type ``.
— The user changed the query input. Fires on every keystroke (not debounced) so consumers can track the latest query and discard stale async results. Consumers that need debouncing should apply it themselves (e.g. Pagefind's debouncedSearch()). detail: { query: string }
result-selected
result-selected is of type ``.
— The user chose a result. detail: { url: string }
search-closed
search-closed is of type ``.
— The overlay was closed (Escape, backdrop click, or result selection). Consumers should use this to cancel in-flight searches or discard pending results. detail: {}
CSS Properties
<esp-search> has the following CSS properties:
--esp-search-max-width
Maximum width of the search panel. Defaults to 40rem.
--esp-search-max-height
Maximum height of the results list. Defaults to 60vh.
--esp-search-backdrop
Backdrop color behind the panel. Defaults to oklch(0.15 0 0 / 0.6).
--esp-search-panel-background
Background color of the search panel. Defaults to var(--esp-color-layer-1).
--esp-search-panel-shadow
Box shadow of the search panel.
--esp-search-border-color
Divider and loading-track color used by the search panel. Defaults to var(--esp-color-border).
--esp-search-text-color
Main text color used by the search UI. Defaults to var(--esp-color-text).
--esp-search-muted-color
Muted text color for placeholders, excerpts, and empty states.
--esp-search-title-color
Title color for result rows. Defaults to var(--esp-color-headings).
--esp-search-active-background
Background color of the active result row. Defaults to var(--esp-color-layer-2).
--esp-search-highlight-background
Background color applied to <mark> highlights inside excerpts.
--esp-search-loading-indicator-color
Accent color of the loading spinner. Defaults to var(--esp-color-primary).
--esp-search-loading-indicator-track-color
Track color of the loading spinner. Defaults to var(--esp-search-border-color).
--esp-field-background
Background color of the shared field shell. Defaults to var(--esp-color-layer-2).
--esp-field-border-color
Border color of the shared field shell. Defaults to var(--esp-color-border).
--esp-field-border-width
Border width of the shared field shell. Defaults to 1px.
--esp-field-text-color
Text color used inside the shared field shell. Defaults to var(--esp-color-text).
--esp-field-hover-bg
Hover background color of the shared field shell. Derived from --esp-field-background.
--esp-field-focus-bg
Focus background color of the shared field shell. Derived from --esp-field-background.
--esp-field-focus-shadow
Shadow color used for shared field focus treatment. Defaults to var(--esp-color-shadow).