Search

When to use

Use search for the one field on a page whose job is finding something, such as a site-wide search bar or a filter box above a list or table. It builds on input, adding search-specific behavior such as a keyboard shortcut and an optional command-palette panel. For a plain text field with no search semantics, use input directly instead.

Install & usage

Pick a framework in the toolbar above and these snippets adapt.

npm install @eunomia/elements

import "@eunomia/elements/search.js";

<eun-search clearable name="search" placeholder="Search…" shortcut></eun-search>

npm install @eunomia/elements

<script type="module">
  import "@eunomia/elements/search.js";
</script>

<eun-search clearable name="search" placeholder="Search…" shortcut></eun-search>

npm install @eunomia/elements

import "@eunomia/elements/search.js";

function SiteSearch() {
  return <eun-search clearable name="search" placeholder="Search…" shortcut />;
}

npm install @eunomia/elements

"use client";
import "@eunomia/elements/search.js";

export function SiteSearch() {
  return <eun-search clearable name="search" placeholder="Search…" shortcut />;
}

npm install @eunomia/elements

<script setup>
  import "@eunomia/elements/search.js";
</script>

<template>
  <eun-search clearable name="search" placeholder="Search…" shortcut />
</template>

npm install @eunomia/elements

import { CUSTOM_ELEMENTS_SCHEMA, Component } from "@angular/core";
import "@eunomia/elements/search.js";

@Component({
  selector: "app-site-search",
  template: `<eun-search
    name="search"
    placeholder="Search…"
    shortcut
  ></eun-search>`,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class SiteSearchComponent {}

Alternatives

Guidance

Live testing

Properties

Basic

<eun-search clearable name="search" placeholder="Search…"></eun-search>

Display

Custom icon

icon (inherited from eun-input, defaulting here to a search glyph) still accepts any other eun-icon name.

<eun-search
  clearable
  name="search"
  icon="saved_search"
  placeholder="Search…"
></eun-search>

Need something other than a eun-icon, or a different icon library entirely? Slot your own content into icon instead ; it replaces the prop-driven icon entirely (the compact panel trigger button, when used, keeps showing the plain icon glyph, since it can't project the same slotted node a second time).

<eun-search clearable name="search" placeholder="Search…">
  <svg
    slot="icon"
    width="16"
    height="16"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    stroke-width="2"
  >
    <circle cx="11" cy="11" r="7"></circle>
    <path d="m20 20-3.5-3.5"></path>
  </svg>
</eun-search>

Appearance

appearance (inherited from eun-input) selects the visual style: outline (default, bordered box), flat (muted background, no border), or underline (bottom border only), the same three appearances as every other text-like field in the library.

<eun-search
  clearable
  name="search"
  placeholder="Flat"
  appearance="flat"
></eun-search>

With panel set, the collapsed trigger button mirrors the same appearance, since it's a separate, hand-rolled element (not the inherited field itself), kept in sync with its own styling rather than looking like outline regardless of what's set:

<eun-search
  clearable
  name="search"
  placeholder="Flat"
  panel
  appearance="flat"
></eun-search>

Part of the shared vocabulary, alongside every other component that reuses it.

Keyboard shortcut

<eun-search clearable name="search" placeholder="Search…" shortcut></eun-search>

This demo leaves out shortcut so it doesn't compete with the documentation site's own header search, which already owns Ctrl+K/⌘K on every page (including this one). Press it now to try the real thing. On a page with a single search field, add shortcut as shown above.

Pressing Ctrl+K (or ⌘K on Mac) anywhere on the page focuses the field. The key-hint badge inside the field is purely decorative (aria-hidden), while the field itself carries aria-keyshortcuts="Control+K Meta+K" while shortcut is set (see the Accessibility tab).

A hidden search field ignores the shortcut, whether it is hidden with display: none itself or through one of its ancestors. A responsive layout can therefore render a full field and a compact one, both with shortcut, and only the one shown at the current breakpoint answers Ctrl+K.

The badge's displayed label, ⌘K versus Ctrl+K, depends on the operating system the browser itself reports, not on real device detection: it reads navigator.userAgentData.platform (falling back to the older, deprecated navigator.platform on browsers without User-Agent Client Hints support) and shows ⌘K for anything reporting a Mac-family platform, Ctrl+K otherwise. Both keyboard shortcuts (Control+K and Meta+K) are always listened for regardless of the detected platform, since only the visual badge adapts. A Mac keyboard connected to a non-Mac machine (or a browser/OS spoofing its reported platform) still triggers the shortcut correctly even if the badge itself shows the "wrong" one.

Modal panel

This demo also leaves out shortcut, for the same reason as the "Keyboard shortcut" example above. See its note, and the Guidance section on the Overview tab.

<eun-search clearable name="search" placeholder="Search…" shortcut panel>
  <ul slot="results" id="results"></ul>
</eun-search>

const search = document.querySelector("eun-search");
const results = document.querySelector("#results");

search.addEventListener("eunchange", () => {
  // Re-render #results from search.value — the field inside the panel
  // shares the same `value`/`eunchange` as the inline field.
});

// From a result's click handler, once selected:
search.closePanel();

With panel set, the visible field becomes a trigger button, and clicking it (or Ctrl+K) opens a eun-modal[kind="search"] containing the real, editable field plus the results slot: a flush, full-width layout (no padding, no border, no close button) with the field's own bottom border separating it from the result list below. See eun-modal's own "Search and command palette" example for the layout on its own. The field carries an Esc badge instead of the collapsed trigger's Ctrl+K/⌘K one, since Escape is how the panel closes once open. Typing in the panel still updates value and fires eunchange exactly like the inline field would, but the trigger button itself stays static: it always shows placeholder, never the current value, since it's purely an entry point into the panel rather than a second display of what's typed there.

Custom trigger

Slot your own element in trigger to replace the built-in trigger, for example an icon button in a top bar. A click on it opens the panel, and closing the panel returns focus to it. The built-in trigger is then no longer rendered, focusable or announced. Give the slotted element its own accessible name. To restyle the built-in trigger instead, target its trigger part.

<eun-search clearable placeholder="Search…" panel>
  <eun-button slot="trigger" icon="search" aria-label="Search"></eun-button>
  <ul slot="results" id="results"></ul>
</eun-search>

eun-search::part(trigger) {
  border-radius: 999px;
}

Suggestions

Set suggestions to open a dropdown listbox of matching option children as the user types, highlighting the matched substring: light DOM option (and optgroup) children, parsed and filtered exactly like eun-select's own. Picking a suggestion sets value to its label and closes the dropdown. eunchange fires with that label, like a keystroke would, then eunselect fires with the option's value attribute as key, so a pick can be told apart from typing, and two options sharing a label stay distinguishable.

<eun-search clearable name="search" placeholder="Search…" suggestions>
  <option>Getting started</option>
  <option>Installation</option>
  <option>Components</option>
  <option>Theming</option>
  <option>Accessibility</option>
</eun-search>

Not supported together with panel, since a collapsed trigger button plus two independent top-layer light-dismiss surfaces (the modal's own and the listbox popover's) isn't a combination this component implements. suggestions is silently ignored while panel is set.

Remote results

When a server returns the results, set filter="none" so the field shows the options as they are instead of filtering them again on their label, which would hide a result the server matched on another field. Replace the option children whenever a response comes back, and the dropdown follows. Listen to eunselect to open the picked result.

<eun-search
  clearable
  name="search"
  placeholder="Search…"
  suggestions
  filter="none"
></eun-search>

import { debounce } from "@eunomia/elements";

const search = document.querySelector("eun-search");

const runSearch = debounce(async (query: string) => {
  search.loading = true;
  try {
    const results = await fetchResults(query); // your own API call
    search.replaceChildren(
      ...results.map((result) => new Option(result.title, result.id)),
    );
  } finally {
    search.loading = false;
  }
}, 300);

search.addEventListener("input", () => runSearch(search.value));
search.addEventListener("eunselect", (event) => openResult(event.key));

Dropdown positioning, sizing, and theming

Same mechanic as eun-select's own dropdown, sharing its CSS custom properties. AnchorPositionMixin keeps the panel positioned against the field on every scroll/resize, flipping above it when there isn't room below, via CSS Anchor Positioning natively where supported and a JS fallback everywhere else. See eun-select's own "Dropdown panel: rendering, positioning, and sizing" section (Examples tab) for the full explanation, including --eun-viewport-inset-top/-bottom for page chrome like a sticky header. --field-listbox-max-height (default 260px) caps how tall it gets before scrolling, --field-listbox-border-radius rounds its corners without following --field-border-radius, while --field-match-color/-background/-font-weight/ -text-decoration theme the highlighted substring. Set any of these once and both eun-search and eun-select pick it up.

Loading

Set loading while a search request is in flight, and a spinning eun-loader replaces the clear button/shortcut badge, without disabling the field, since a live search commonly keeps accepting input while the request for the previous keystroke is still in flight.

<eun-search clearable name="search" placeholder="Search…" loading></eun-search>

import "@eunomia/elements/loader.js";

eun-loader is used internally, but its module must still be imported alongside eun-search for the spinner to render, exactly like eun-icon for the leading icon above.

With panel set, loading is ignored on both the collapsed trigger button and the panel's own field, which both stay static entry points regardless of a request in flight. Reflect the loading state on the results slot instead, as in the "Debouncing a real request" example below.

Debouncing a real request

eun-search has no idea what "the request" behind loading actually is, since that's entirely the consumer's own code, wired to eunchange. Debouncing it so a fast typist doesn't fire one request per keystroke is that same consumer's responsibility too, so @eunomia/elements exports a small debounce helper for exactly this, meaning nobody has to reach for a whole utility library (like Lodash) just for this one function, or reimplement it by hand.

This example puts the two together inside panel's results slot: typing debounces, loading shows while the (simulated) request is in flight, with a eun-loader replacing the result rows entirely instead of leaving stale or empty content on screen, then the real rows replace it once the response is back. This is exactly why loading stays invisible on the trigger and the panel's own field in panel mode: the list is where the in-flight state actually belongs, not duplicated onto the field above it.

<eun-search clearable name="search" placeholder="Search…" panel>
  <ul slot="results" id="results"></ul>
</eun-search>

import { debounce } from "@eunomia/elements";

const search = document.querySelector("eun-search");
const results = document.querySelector("#results");

const runSearch = debounce(async (query: string) => {
  search.loading = true;
  try {
    const matches = await fetchResults(query); // your own API call
    renderResults(matches); // your own rendering, e.g. a eun-loader row while empty
  } finally {
    search.loading = false;
  }
}, 300);

search.addEventListener("eunchange", () => runSearch(search.value));

300ms is a reasonable starting point for a debounce delay on a live search, long enough to skip firing on every keystroke of a fast typist, yet short enough to still feel immediate. Tune it against your own API's actual latency.

Server-side rendering

The field is drawn inside the search's shadow root, so a server-rendered search takes no space until the element upgrades, then pushes aside what follows it. Link field-ssr.css in the page's <head> to draw it from the first paint, search icon included:

<link
  rel="stylesheet"
  href="node_modules/@eunomia/elements/dist/ssr/field-ssr.css"
/>

It's the same stylesheet as eun-input's, reading the same attributes. The suggestion options stay hidden until the upgrade. The panel trigger isn't drawn before the upgrade.

Custom colors

The custom properties that change colors, borders, shadows and corners, at a glance. The API tab lists every property of the component.

Keyboard interactions

While suggestions is set (inline only):

Semantics and screen readers

Aria attributes

The key-hint badge (⌘K/Ctrl+K/Esc) is purely decorative and marked aria-hidden="true" in every context it appears. The actual describable shortcut lives on whichever element it really activates:

• Inline (panel not set): the field itself carries aria-keyshortcuts="Control+K Meta+K" while shortcut is set.
• Panel mode: the trigger button carries aria-keyshortcuts instead, since the real field sits inside a closed popover until opened, and content inside a closed popover is removed from the accessibility tree entirely, so describing the shortcut there wouldn't be discoverable. The trigger button also carries aria-haspopup="dialog".

The panel's dialog (eun-modal[kind="search"]) renders no visible heading, so it wouldn't otherwise have an accessible name. eun-search sets a plain aria-label on it directly: label when set (naming the dialog the same as the field), falling back to panelLabel (default "Search") otherwise. See eun-modal's own Accessibility tab for the dialog's other semantics (role="dialog", focus handling, Escape), which also covers focus management in more depth, including this component's own case: the panel's field gets autofocus so keyboard focus lands there immediately on open, and closing it (however that happens) returns focus to wherever it was before, either the trigger button if that's what opened it, or elsewhere on the page if a global Ctrl+K/⌘K press did.

Suggestions are a combobox

While suggestions is set (inline only), the field follows the WAI-ARIA APG combobox pattern with list autocomplete, like a searchable eun-select:

• role="combobox", aria-autocomplete="list", aria-controls="listbox" and aria-expanded="true"\|"false" on the field
• aria-activedescendant on the field, set to the highlighted suggestion while one is highlighted, so a screen reader announces it without moving the DOM focus off the field
• role="listbox" on the dropdown, named from the field's label, with role="option" / aria-selected on each suggestion, and the suggestions of each optgroup wrapped in a role="group" named by its label

Results are not a combobox/listbox

The results slot is fully consumer-defined content (any markup, a list, a grid, grouped sections), and eun-search doesn't know its shape, so it doesn't implement the ARIA combobox/listbox pattern (role="combobox", aria-expanded, aria-controls, aria-activedescendant, arrow-key roving focus between results). Tab still reaches every result normally, same as any other focusable content, but there's no arrow-key navigation between them out of the box. If you need that, implement roving tabindex / aria-activedescendant yourself on your own slotted markup, following the ARIA combobox pattern.

Reference links

WAI-ARIA Dialog (Modal) Pattern
WAI-ARIA Combobox Pattern
MDN: aria-keyshortcuts