Themeable, pluggable command-palette search UI for static sites, powered by Pagefind.

Overview

Hawk is a themeable, pluggable command-palette search widget for static sites: npm install + a constructor call, no host markup beyond a trigger element required. Pagefind owns indexing, ranking, and typo-tolerant matching; hawk owns the modal, keyboard navigation, and result rendering, with visual theme and reveal animation as swappable plugins rather than hardcoded choices.

Full usage, configuration, and theming detail lives in the docs site linked below — this README stays a short pitch plus what you need to build the project from source.

---

🔹 Read the full documentation here

🔹 Use the playground here

📚Table of Contents

• Overview
• Features
• Installation
• Quick start
• Build from source
• Acknowledgments
• Resources
• Contributing
• Links
• Development & NPM Scripts
• License

Features

• Pagefind-backed — chunked, lazily-loaded, typo-tolerant search index.
• Scale-safe result hydration — bounded concurrent fragment loading and progressive rendering keep Hawk's network and DOM work predictable for both small and very large indexes.
• Developer-configured tabs — auto-derived category pills, or explicit Pagefind-filter tabs.
• Fit / medium / compact density modes with a persisted in-modal toggle.
• Two-pane keyboard navigation — Tab between input, filters, results, and preview.
• Configurable layout — scale, position, offset, columns, and a JS-driven breakpoint.
• Theme and animation plugin systems — a TypeFlow typewriter driver ships built-in, alongside a zero-dependency instant driver.
• Structured inline filters — category:Guides responsive parses out a filter as you type.
• Result metadata — dates, tags, related pages, and a pin system, each independently themeable and configurable.
• Built-in trigger element and Pagefind attribution, so no hand-built markup is required.
• Accessible by default — a real modal focus trap, graceful fallback if Pagefind fails to load, and full i18n via config.strings.

See Resources below for the full feature reference.

Installation

npm install @staticcanvas/hawk
npm install --save-dev pagefind
# Optional: the official TypeFlow animation driver
npm install @staticcanvas/typeflow

pagefind is a real dependency (hawk has nothing to search without an index). @staticcanvas/typeflow is an optional peer dependency — only needed when importing Hawk's official TypeFlow animation adapter. Hawk core and the TypeFlow visual theme remain independent.

Quick start

import { HawkSearch } from '@staticcanvas/hawk';
import '@staticcanvas/hawk/css';

new HawkSearch({
  index: '/pagefind/',
  trigger: { container: 'body' },
});

Hawk hydrates Pagefind result fragments in ordered batches: up to 6 requests run concurrently, the first completed batch renders immediately, and loading stops once maxResults is filled. Large or exclusion-heavy indexes are bounded to maxCandidateResults candidates (by default, three times maxResults). Both limits are configurable; see the API reference.

That is the complete zero-config path — trigger renders hawk's own trigger button, so no host markup is required. See Getting started in the docs for the full TypeFlow-themed setup, frontmatter/metadata mapping, and every config option.

Build from source

git clone https://gitlab.com/staticcanvas/hawk.git
cd hawk
npm install
npm run build   # core + optional (theme-typeflow, animation-typeflow, debug, metrics) bundles
npm test        # vitest, jsdom

To build and preview the docs site itself (Hugo + Pagefind, requires Hugo on PATH):

npm run docs:serve

See Development & NPM Scripts for the full script reference.

Acknowledgments

Hawk's development and distribution are supported by these services:

• jsDelivr — open-source CDN delivery.
• UNPKG — CDN delivery for npm packages.
• npm — package registry and distribution.
• JSR — JavaScript and TypeScript package registry.
• Shields.io — project and status badges.
• GitLab — source hosting, CI/CD, releases, and documentation hosting.
• Codecov — test coverage reporting.

Resources

• Documentation: https://staticcanvas.gitlab.io/hawk/
• Playground: https://staticcanvas.gitlab.io/hawk/playground/
• API reference: docs/content/api.md
• Guides: Pagefind setup, tabs, and inline filters · Density and keyboard navigation · Theming · Animation plugins · Pins, the built-in trigger, and attribution
• Architecture: architecture/README.md (design rationale) · plugin-system.md · theme-interface.md · animation-driver-interface.md
• Changelog: CHANGELOG.md
• Issues: https://gitlab.com/staticcanvas/hawk/-/issues

Contributing

Contributions are welcome. For a substantial change, first open an issue to discuss the proposal. For smaller fixes:

1. Fork the project, then clone your fork: git clone https://gitlab.com/YOUR_USERNAME/hawk.git.

2. Enter the checkout: cd hawk.

3. Install the locked dependencies: npm ci.

4. Create a branch from develop: git switch develop && git switch -c feature/feature-name.

5. Make your changes, then run npm run lint and npm test.

6. Commit and push: git commit -m 'Add feature name' && git push -u origin feature/feature-name.

7. Open a merge request targeting develop:

   

Links

• GitLab repository
• Issue tracker
• npm package
• JSR package

Development & NPM Scripts

Script	Purpose
npm run dev	Vite dev server
npm run serve:demo	Opens the local web utility demo in Vite
npm run build	Builds core + optional (theme-typeflow, animation-typeflow, debug, metrics) bundles
npm run dev:typeflow	Builds hawk and copies the bundle + a preview Pagefind index into the sibling typeflow checkout's docs site, for live prototyping
npm run pagefind:index	Wraps pagefind --site <dir> — see scripts/pagefind-index.mjs
npm test / npm run test:coverage	Vitest (jsdom) — unit coverage
npm run test:bun / npm run test:coverage:bun	Bun test runner, with optional coverage
npm run test:e2e	Playwright, real Chromium against a real built docs site + Pagefind index (not a fixture) — builds the docs site with a localhost baseURL override first. Runs in CI as test:e2e (allow_failure: true until it's proven stable there — see .gitlab-ci.yml).
npm run lint / npm run lint:fix	ESLint
npm run format	Formats the repository with Prettier
npm run docs:build / npm run docs:serve	Builds and serves hawk's own Hugo docs site
npm run themes:css	Generates one small standalone CSS file per gallery/template theme into docs/static/assets/themes/ — see scripts/generate-theme-css.mjs
npm run docs:scss	Compiles docs/static/assets/scss/*.scss into docs/static/assets/docs.css/playground.css — see scripts/compile-docs-scss.mjs. Also runs automatically as part of docs:build/docs:serve
npm run check:size	Enforces the gzip bundle size budget
npm run check:jsr	Validates the JSR package configuration and dry-run contents
npm run validate:release	CI release-artifact validation
npm run check:quality	Builds, checks the bundle size, and runs the Vitest suite
npm run bench:size	Compares bundle sizes against a selected Git reference

License

Distributed under the MIT License. See LICENSE for details.