hp-background

Faint hex-grid backdrop that brightens softly around the pointer. Lives as an absolutely- positioned child inside any container, sitting beneath the foreground content. Strokes are --hp-outline-faint at rest; a radial mask reveals a brighter copy (--hp-outline) only within a configurable pixel radius of the cursor.

Examples

API

Intent

Changelog

Move the cursor across the canvas to see the brightening trail.

hp-background as a sibling of the grid cells inside an hp-grid. The grid's drag / pan behaviour is unaffected — the backdrop has pointer-events: none, so cells and pan still receive the pointer.

centre

east

west

north

south

<body> <hp-grid draggable> <hp-background></hp-background> <hp-cell variant="anchor" q="0" r="0">centre</hp-cell> <hp-cell variant="action" q="1" r="0">east</hp-cell> </hp-grid> </body>

Install

bun add @hexpunk/core lit

import "@hexpunk/core";

Properties

Property	Attribute	Type	Default	Description
`hexSize`	`hex-size`	`number`	`14`	Hex side length in pixels (centre-to-vertex). Smaller = denser pattern. Default 14 — reads as ambient texture, not a focal element.
`pointerRadius`	`pointer-radius`	`number`	`200`	Radius in pixels where the brighter strokes are fully visible around the cursor. Falls to transparent at the edge. Default 200.

CSS Custom Properties

Property	Default	Description
`--hp-bg-stroke`	—	Base stroke colour
`--hp-bg-stroke-bright`	—	Cursor-halo stroke colour
`--hp-bg-faint-opacity`	—	Base layer opacity (default 0.25)
`--hp-bg-bright-opacity`	—	Halo layer opacity (default 0.3)
`--hp-bg-pointer-radius`	—	Pixel radius of the cursor halo

When to use

Use as the backdrop for any surface that benefits from ambient hex texture — demo canvases, dashboards, the document body. The pointer-aware brightening reads as "this surface notices you" without competing with the foreground.

Tune hex-size to the surface scale. ~10-14 for small canvases, 18-24 for full-viewport / hero areas.

Set the parent container position: relative so the backdrop's inset: 0 stretches to fill it.

Stack multiple hp-backgrounds in the same stacking context — the interference patterns get noisy and the pointer-following overlays compound visually.

Use as foreground content. The element is aria-hidden and pointer-events: none — it's never the thing the user is meant to interact with.

Performance

Polygons are rendered once on mount (and re-rendered on resize). Pointer tracking is a single window-level pointermove listener that writes two CSS variables — no per-frame DOM updates beyond the style set. The radial-gradient mask is GPU- compositied. Several hundred hexes is comfortable; thousands start to show in paint cost on lower-end hardware (increase hex-size to reduce density).

Accessibility

Auto aria-hidden="true" on the host — the element is purely decorative and never announces. Respects prefers-reduced-motion: the bright cursor- following layer is suppressed (faint base still renders), so the surface stays calm for users who've opted out.

0.1.0-beta 2026-05-24
Added
- <hp-latex> — render-only LaTeX math primitive. Consumer-registered renderer via HpLatex.setRenderer((latex, "inline" | "block") => string | null); @hexpunk/core has zero math-engine dependency. value attribute carries the LaTeX source (text content fallback captured once on connect). Boolean attributes: block (block/display mode, centred + full-width), background (mounts <hp-background> backdrop inside the element, block mode only), copyable (mounts <hp-copy> source button in the top-right corner, block mode only). Without a renderer, source renders mono-spaced fallback; render-error CustomEvent dispatches on renderer throw. Only light-DOM hp-\* element in the system — required for KaTeX's class-scoped CSS to cascade into the rendered output (file header explains the rationale). Not SSR-friendly via @lit-labs/ssr; consumers wanting pre-rendered math in MDX use Astro's remark-math + rehype-katex directly.