API Reference

Complete documentation for the <border-wc> web component and the data-border-effect attribute binder.

Install

npm install @profpowell/border-wc

Import the element. It self-registers as <border-wc> on import:

import '@profpowell/border-wc';

Or via a CDN:

Element — `<border-wc>`

Wraps an element with an extreme border effect. The component reads design tokens and updates live as attributes change.

<border-wc effect="squiggle" color="var(--ink)" animate> <blockquote>The shape around the thing is the thing.</blockquote> </border-wc>

Attributes

Attribute	Description
`effect`	One of thirty-two effects — see the Effects catalog below.
`color`	Stroke / particle color (any CSS color; defaults to `currentColor`).
`thickness`	Stroke width in px (default 2).
`speed`	Animation duration in ms (default 1000).
`radius`	Corner radius in px. Falls back to the host's computed `border-radius`.
`animate`	Boolean. When present, plays the entrance / loop animation.
`mode`	Effect-specific placement mode (e.g. `center`).
`trigger`	Effect-specific reveal trigger (e.g. `time` \| `scroll` on `draw`).
`motion`	`auto` \| `reduce` \| `force` — overrides `prefers-reduced-motion`.

CSS custom properties

Every attribute can also be set via a matching --border-wc-* custom property, which takes precedence over the attribute. Use these to theme the effect from the cascade:

.fancy { --border-wc-color: oklch(0.7 0.18 250); --border-wc-thickness: 3px; }

Events

border-wc:effect-applied — fired once after a successful apply. detail.effect is the effect name.
border-wc:error — fired if an effect throws. detail.error is the error.
border-wc:draw-complete — fired by the draw effect when the stroke animation finishes.

Effects catalog

Nineteen effects ship today, grouped into seven families. Each behaves under prefers-reduced-motion: reduce — motion-heavy effects render a static end-state, one-shot effects skip the reveal animation.

Effect	Family	Renderer	Notes
`aurora`	Modern CSS	div + conic-gradient	Rotating multi-stop halo via `@property --bwc-angle`; blurred sibling glow.
`barber`	Modern CSS	div + repeating-linear	Scrolling diagonal stripes; `mode="warning \| candy \| racing"` presets.
`chroma`	Modern CSS	host box-shadow	8-direction chromatic-aberration shadow stack on the host element.
`wings`	Modern CSS	div + clip-path	Two oversized colored triangles morphing behind the card; `mix-blend-mode: multiply`.
`ants`	Modern CSS	svg	Photoshop-style marching-ants selection — animated `stroke-dashoffset` with white underlay.
`lightning`	Energy	svg + feGaussianBlur	Jagged glowing bolts at evenly-spaced anchor points; refactored from canvas in 0.2.
`neon`	Energy	svg + feMerge	Crisp stroked path with a real `feGaussianBlur+feMerge` halo (SMIL pulse). `mode="synthwave"` swaps the stroke for a 3-stop cyan→magenta→orange gradient, widens the bloom, and adds a sweeping horizontal scanline.
`glitch`	Energy	svg	RGB-split stroked paths with random offsets.
`hud`	Energy	svg + div	Cyberpunk FUI: corner brackets + edge tick-marks + sweeping scan line. Host left untouched.
`ascii`	Retro/Craft	svg text	Monospace + - \| characters at corners and edges (one-shot reveal).
`stitching`	Retro/Craft	svg	Dashed stitches sew themselves around the perimeter.
`typewriter`	Retro/Craft	svg text	Per-char reveal; use `data-text` on the host for custom glyphs.
`barbed-wire`	Pattern	svg	Wire path + rotated four-point barbs.
`rope`	Pattern	svg	Two offset dashed strands suggesting a twist.
`scallop`	Pattern	svg	Half-circle bumps oriented along the outward normal.
`scoop`	Pattern	svg	Inverse of scallop: concave bites cut into each edge (postage-stamp from the back). One-shot dashoffset reveal.
`zigzag`	Pattern	svg	Sawtooth perimeter; optional marching-dashes loop.
`wave`	Pattern	svg	Smooth sine perimeter via quad beziers; optional marching-dashes loop.
`deco`	Pattern	svg	Art Deco: double stroked perimeter + radiating sunburst fans at each corner.
`memphis`	Pattern	svg	Memphis confetti: arc-length sampler scatters mixed shapes with staggered bob animation.
`opart`	Pattern	div + mask-composite	Op-Art moiré ring: crossed `repeating-linear-gradient` stripes masked into a perimeter band, shifted for shimmer.
`psychedelic`	Trippy	svg	Rainbow gradient stroke + hue-rotate + marching dashes.
`plasma`	Trippy	canvas	HSL-cycling glow piecewise along the perimeter.
`gooey`	Trippy	svg + feColorMatrix	Metaball ring: feGaussianBlur + alpha-boost ColorMatrix merge blobs orbiting along the perimeter via `offset-path`.
`sparks`	Marquee	svg + offset-path	Comet-tail circles orbiting via `offset-path`; refactored from canvas in 0.2.
`marquee`	Marquee	svg	Chase-light bulbs with staggered keyframes; `mode="chase \| sparkle \| random"`.
`washi`	Decoration	div + svg filter	Tape strips on the host (not a perimeter). `mode="corner \| corners \| top \| bottom \| left \| right \| span \| scatter"`. Tunables via `--washi-pattern` (stripe/solid/dot/check/grid), `--washi-torn` (fray/soft/straight), `--washi-width`, `--washi-length`, `--washi-angle`, `--washi-count`, `--washi-opacity`, `--washi-color-2`.
`filmstrip`	Decoration	div	Two sprocket-hole bars top + bottom (radial-gradient pattern). Body untouched.
`ticket`	Decoration	svg	Notched perimeter (semicircle dips at ~70% along top/bottom) with a dashed tear line. Body fill is in the SVG.
`bunting`	Decoration	svg	Pennant flags hanging from a quadratic swag along the top edge; each pennant sways with a staggered delay.
`squiggle`	Originals	svg + feTurbulence	Hand-drawn turbulence on a stroked path.
`draw`	Originals	svg	One-shot stroke-on reveal (fires `border-wc:draw-complete`). `trigger="scroll"` drives the reveal via `animation-timeline: view()` as the host enters the viewport; degrades to a fully-drawn border on engines without scroll-driven animations.

Modern CSS notes

A few effects rely on browser features that have arrived since 2024. They degrade gracefully when missing:

aurora registers a global @property --bwc-angle for smooth conic-gradient rotation. On Firefox < 128 the gradient stays at a fixed angle.
chroma mutates host.style.boxShadow (captures the previous value, restores on cleanup). If your host already sets a box-shadow for its own styling, expect it to be overridden while the effect is active.
sparks uses CSS offset-path. Universal in evergreen browsers; falls back to a stationary dot otherwise.
barber accepts mode="warning | candy | racing"; marquee accepts mode="chase | sparkle | random".
color accepts a comma-separated list for multi-stop effects (aurora, barber, wings, chroma). Single colors and currentColor still work.

Attribute binder — `data-border-effect`

border-wc shares the data-border-effect attribute with vanilla-breeze's base tier. Base values (spin, pulse, march, hue-cycle, breathe, corner-trace) are owned by vanilla-breeze's CSS — border-wc ignores them. Extreme values — the thirty-two effects in the catalog above — are handled here.

To opt in to extreme effects without writing a <border-wc> wrapper, import the binder once:

import '@profpowell/border-wc/attr';

Then annotate any element:

Params come from --border-wc-* CSS custom properties (the same set as on the element). The binder auto-scans on import and watches the DOM for added / changed / removed nodes.

Used with vanilla-breeze

border-wc is the extreme-tier sibling of vanilla-breeze's base border tier — together they form the "Decorated Layers" border surface. Pair this package with vanilla-breeze for CSS-only base effects (spin, pulse, …) and reach for <border-wc> / the binder when you need SVG / canvas-driven effects. Both honor data-border-effect, so authors write one attribute.