@md-plugins/search-ui

Framework-agnostic search UI for search indexes generated by @md-plugins/vite-search-plugin. Q-Press uses it for header search, and non-Q-Press sites can use the same Web Component against a generated JSON index or a custom provider.

The package provides:

• a static JSON search provider for search/search-index.json
• normalized search result types
• the <md-search> Web Component
• CSS custom properties and part attributes for site-specific styling
• an icon-only mobile trigger that keeps search available in narrow headers

Installation

pnpm add @md-plugins/search-ui

Static JSON Usage

import { defineMdSearchElement } from '@md-plugins/search-ui'

defineMdSearchElement()

<md-search src="/search/search-index.json"></md-search>

Search results collapse duplicate records by default. This keeps generated heading/content pairs that point to the same URL from appearing twice in the panel. Add show-duplicate-results when you want to inspect the raw index output:

<md-search src="/search/search-index.json" show-duplicate-results></md-search>

Styling

The component uses Shadow DOM, CSS custom properties, and part attributes:

md-search {
  --md-search-accent: #1976d2;
  --md-search-surface: white;
  --md-search-text: #102033;
  --md-search-radius: 14px;
}

md-search::part(dialog) {
  box-shadow: 0 24px 80px rgb(0 0 0 / 24%);
}

The component supports light and dark modes. By default it follows prefers-color-scheme. Use the theme attribute when your application owns the active theme:

<md-search src="/search/search-index.json" theme="dark"></md-search>

Use theme="light" to force light mode. Site CSS variables can still override either theme.

Accessibility

<md-search> includes keyboard and screen-reader support:

• Ctrl+K / Cmd+K opens the search by default.
• Escape closes the dialog.
• ArrowUp and ArrowDown move between results.
• Enter selects the active result.
• The dialog uses role="dialog" and aria-modal.
• The input exposes combobox/listbox relationships through ARIA attributes.
• Result rows use role="option" and update the active descendant.

Use search-label to provide a project-specific input label:

<md-search src="/search/search-index.json" search-label="Search product documentation"></md-search>

Custom Providers

import { createSearch } from '@md-plugins/search-ui'

createSearch({
  target: document.querySelector('#search')!,
  provider: {
    async search(query) {
      return mySearchService(query)
    },
  },
})