🔹 Read the full documentation here
🔹 Use the playground here
📚Table of Contents
- 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 responsiveparses 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.
npm install @staticcanvas/hawk
npm install --save-dev pagefind
# Optional: the official TypeFlow animation driver
npm install @staticcanvas/typeflowpagefind 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.
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.
git clone https://github.com/staticcanvas/hawk.git
cd hawk
npm install
npm run build # core + optional (theme-typeflow, animation-typeflow, debug, metrics) bundles
npm test # vitest, jsdomTo build and preview the docs site itself (Hugo + Pagefind, requires
Hugo on PATH):
npm run docs:serveSee Development & NPM Scripts for the full script reference.
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.
- GitHub — source hosting, CI/CD, releases, and documentation hosting.
- Codecov — test coverage reporting.
- Documentation: https://staticcanvas.github.io/hawk/
- Playground: https://staticcanvas.github.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://github.com/staticcanvas/hawk/issues
Contributions are welcome. For a substantial change, first open an issue to discuss the proposal. For smaller fixes:
-
Fork the project, then clone your fork:
git clone https://github.com/YOUR_USERNAME/hawk.git. -
Enter the checkout:
cd hawk. -
Install the locked dependencies:
npm ci. -
Create a branch from
develop:git switch develop && git switch -c feature/feature-name. -
Make your changes, then run
npm run lintandnpm test. -
Commit and push:
git commit -m 'Add feature name' && git push -u origin feature/feature-name. -
Open a pull request targeting
develop:
| 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 as a required browser check in GitHub Actions. |
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 |
Distributed under the MIT License. See LICENSE for details.
CI and release setup is documented in GitHub Actions.
