Search Component — Astro

Search component with Algolia integration and live filtering

Search Component

An accessible search component that ships local search by default (client-side index, no backend). You can optionally hook up Algolia for hosted search, analytics, and better relevance; when Algolia is configured, the component uses it first and falls back to local search on network errors or if Algolia is unavailable. The package scaffold (when you add Search via the CLI) ships local/static search only: overlay with header (search icon, input, close button), focus trap, click-outside and Escape to close, and example result links you can edit.

Add this component

The command below includes <strong>Search</strong>—run it in your project directory to install this component (and the CSS if needed). No prompts.

Choose your package manager — click a tab to select, then copy the command.

npm pnpm yarn bun

Features

  • Full-screen overlay - When open, the overlay covers the viewport; the search modal is centered inside it both horizontally and vertically
  • Optional Algolia with local search fallback (search and click analytics when Algolia is enabled)
  • Keyboard shortcut - Ctrl+K / Cmd+K to open
  • Close button on desktop (X icon with screen reader label)
  • Close button on mobile with text label
  • Live search results as you type
  • Full keyboard navigation (Arrow keys, Enter, Escape, Tab)
  • Mobile responsive - Full-width panel on mobile
  • Mutually exclusive with mobile menu (only one open at a time)
  • Accessible - ARIA attributes and screen reader support

Live example

Search is in the navbar (top of page) — click the search icon or press Ctrl+K / Cmd+K. You can also use the standalone search below.

Standalone search (same as navbar)

Usage

Search script runs after DOM ready. Ctrl+K / Cmd+K opens it when the component is on the page.

Usage

Full example for each framework (Astro, Vanilla, Svelte, Vue, React). Switch framework via View as or by clicking a Usage tab—both stay in sync.

Astro Vanilla Svelte Vue React

Props

  • useAlgolia (boolean, optional) - Enable Algolia search (default: false)
  • algoliaAppId (string, optional) - Algolia Application ID
  • algoliaApiKey (string, optional) - Algolia Search-Only API Key
  • algoliaIndexName (string, optional) - Algolia index name (default: "rizzo-css-docs")

Keyboard Shortcuts

  • Ctrl+K / Cmd+K - Open/close search
  • Escape - Close search
  • Arrow Down - Navigate to next result
  • Arrow Up - Navigate to previous result
  • Enter - Navigate to selected result

Optional: Hook up Algolia

By default, Search uses a local client-side index (no API keys, works offline). To use Algolia for hosted search, analytics, and better relevance, follow these steps. When Algolia is configured, Search uses it first and automatically falls back to local search on errors or if the network fails.

1. Create an Algolia application

  • Sign up at algolia.com (opens in new tab)
  • Create a new application and note your Application ID
  • In API Keys: copy your Search-Only API Key (for the frontend) and your Admin API Key (for indexing only; never expose in the browser)

2. Index your content

Build a script or use the docs site’s approach: a script that outputs records (title, url, category, content) and uploads them to Algolia. Example for a docs site:

bash bash 
# Install the Algolia client (for the indexing script only)
pnpm add algoliasearch

# Set credentials (use Admin API Key for indexing; never commit)
export ALGOLIA_APP_ID="your-app-id"
export ALGOLIA_ADMIN_KEY="your-admin-api-key"
export ALGOLIA_INDEX_NAME="your-index-name"

# Run your indexing script (e.g. node scripts/index-docs.js)
node scripts/index-docs.js

Each record should have at least objectID, title, url, category, and content so the Search component can display and link results. Run the script after content changes (e.g. in CI or locally before deploy).

3. Enable Algolia in your app

Astro (this docs site): Set environment variables so the Search component picks them up. The component reads PUBLIC_ALGOLIA_APP_ID, PUBLIC_ALGOLIA_SEARCH_KEY, and PUBLIC_ALGOLIA_INDEX_NAME. If both App ID and Search Key are set, Algolia is used automatically with local fallback.

bash bash 
# .env (never commit real keys)
PUBLIC_ALGOLIA_APP_ID=your-app-id
PUBLIC_ALGOLIA_SEARCH_KEY=your-search-only-api-key
PUBLIC_ALGOLIA_INDEX_NAME=your-index-name

# Optional: force-enable even if you want to rely on env elsewhere
# PUBLIC_ALGOLIA_ENABLED=true

Or pass props: You can pass useAlgolia=true, algoliaAppId, algoliaApiKey, and algoliaIndexName to the Search component instead of using env vars.

Svelte / Vanilla: The scaffold ships local search only. To add Algolia, include the Algolia client (or use a small backend that proxies search), maintain a search index (e.g. the same record shape), and either call Algolia from your existing search UI logic or adapt the docs site’s Search.astro client script pattern (Algolia first, local fallback on error).

4. Analytics

When Algolia is enabled, the Search component sends click analytics (which result was clicked after which query) so you can see popular queries and results in the Algolia dashboard. Search requests use clickAnalytics: true so Algolia can track and improve relevance.

Accessibility

The Search component includes comprehensive accessibility features:

  • ARIA Roles: role="dialog", role="listbox", role="option"
  • ARIA Labels: Descriptive labels for all interactive elements
  • Keyboard Navigation: Full keyboard support for all interactions
  • Focus Management: Focus trapping and restoration
  • Screen Reader Support: Proper announcements and labels
  • Live Regions: Search results announced to screen readers

Other frameworks: Vanilla · Svelte · Vue · React