Welcome to Vanilla Breeze
This bell pulls live notifications from /go/notify/messages — the same contract documented at /docs/concepts/service-contracts/. Static articles like this one are the no-JS / no-backend fallback.
bg-wc
A theme-aware graphics layer. <bg-wc> renders an animated WebGL or Canvas2D background behind any HTML content, picking the right renderer per preset. It reads the same --color-* tokens Vanilla Breeze themes set on :root, so it re-skins automatically when you switch theme packs — and it can be applied without writing a custom element at all, via data-background attributes.
Where to find it
- npm:
@profpowell/bg-wc(currently0.2.1— pre-1.0, the API may still shift) - GitHub: ProfPowell/bg-wc
- Docs: profpowell.github.io/bg-wc
- License: MIT
Install
Via CDN:
HTML
<script type="module" src="https://unpkg.com/@profpowell/[email protected]/dist/bg-wc.js"></script>Or via npm:
BASH
npm install @profpowell/bg-wcJAVASCRIPT
import '@profpowell/bg-wc';Not bundled into Vanilla Breeze — wire it in yourself. There is no build coupling between the two repos; the interface is purely CSS custom properties.
Two ways to apply it
1. As a custom element
Wrap your content. The content stays in the light DOM and renders above the animated layer:
HTML
<bg-wc preset="mesh-gradient" intensity="0.65"> <h1>Hero headline</h1> <p>Content sits above the rendered layer.</p> <img slot="fallback" src="hero-static.webp" alt=""/></bg-wc>2. As data-background attributes (no custom element)
Import the binder once, then decorate any existing element with data-background and matching data-background-* attributes. The binder injects a <bg-wc> behind that element's content — handy when you don't want to restructure your markup:
JAVASCRIPT
import '@profpowell/bg-wc/data-background';HTML
<section data-background="mosaic" data-background-mode="isometric" data-background-intensity="0.7" data-background-density="0.55"> <h1>Squares behind any element</h1></section>Add data-background-skip to an element to opt it out of binding. For dynamically inserted DOM, call bindDataBackgrounds(root) after import.
Demos
Each demo loads a default-theme Vanilla Breeze page and fills the frame with a single background. Switching the page's data-theme would re-skin each one, since they read VB tokens directly.
mesh-gradient (WebGL custom element)
mosaic (via the data-background binder)
confetti (Canvas2D, semantic palette)
Attributes
| Attribute | Values | Default | Purpose |
|---|---|---|---|
preset | preset name | — | Required. Which effect to render (see below). |
palette | theme / rainbow / mono | theme | Color strategy. theme pulls VB tokens. |
intensity | 0–1 | 0.5 | Per-preset drama / strength. |
speed | 0–5 | 1 | Time multiplier; 0 freezes the animation. |
density | 0–1 | 0.5 | Particle count or shader detail. |
seed | integer | 0 | Deterministic randomization. |
paused | boolean | unset | Pauses the render loop without unmounting. |
pixel-ratio | number | min(devicePixelRatio, 2) | Override render pixel density. |
quality | low / med / high | med | Renderer-level quality hint. |
fit | cover / contain / stretch | cover | Surface sizing behavior. |
motion | auto / reduce / force | auto | Reduced-motion handling (see below). |
text | string | — | Payload for text presets; lines split on |. |
mode | string | — | Used by mosaic: isometric, flat, sparse, stacked. |
use-theme | boolean | unset | Enables theme-token coloring for system7. |
data-background attributes
After importing @profpowell/bg-wc/data-background, every attribute below maps to the matching <bg-wc> attribute or custom property on the injected element.
| data-* attribute | Maps to |
|---|---|
data-background | preset (required) |
data-background-intensity | intensity |
data-background-speed | speed |
data-background-density | density |
data-background-seed | seed |
data-background-palette | palette |
data-background-quality | quality |
data-background-fit | fit |
data-background-motion | motion |
data-background-paused | paused |
data-background-pixel-ratio | pixel-ratio |
data-background-color-1 | --bg-wc-color-1 |
data-background-color-2 | --bg-wc-color-2 |
data-background-color-3 | --bg-wc-color-3 |
data-background-color-bg | --bg-wc-color-bg |
data-background-color-fg | --bg-wc-color-fg |
data-background-skip | escape hatch — prevents binding |
Presets
Dozens of presets ship across two renderers. The current catalog:
WebGL (shader) presets
dither, noise, mesh-gradient, warp, waves, lava, plasma, aurora, tunnel, caustics, glitch, rainbow, halftone, kaleidoscope, vhs, synthwave, crt, gameboy, copperbars, topology, cells, shine, conic, grain, trench, marble, benday, comic, deco, bliss
Canvas2D presets
| Group | Presets |
|---|---|
| Vector / arcade | asteroids, wireframe, spirograph, incoming, tempest, fireworks |
| Text | crawl, marquee, sinescroll, cascade |
| Dataviz | trades, dashboard, vectormap, scatter, waveform, wordcloud |
| Particles | stars, snow, confetti, network, particles, pulse, tetris, matrix, mystify |
| Pattern / geometric | mosaic, ribbons, source, system7 |
For the live gallery see the component docs.
Theme tokens
The renderer reads these VB tokens once per frame, with built-in fallbacks so it still works on a non-VB page:
| Token | Role | Fallback |
|---|---|---|
--color-background | Canvas backdrop | transparent |
--color-foreground | Default line / particle color | #1a1a1a |
--color-primary | Primary tint | #3b82f6 |
--color-accent | Accent tint | #ec4899 |
--color-info | Tertiary tint | #10b981 |
--color-success / --color-warning / --color-error | Semantic palette (e.g. confetti) | green / amber / red |
Per-instance overrides via the component's own namespace always win:
| Property | Overrides |
|---|---|
--bg-wc-color-1 | --color-primary |
--bg-wc-color-2 | --color-accent |
--bg-wc-color-3 | --color-info |
--bg-wc-color-bg | --color-background |
--bg-wc-color-fg | --color-foreground |
--bg-wc-intensity / --bg-wc-speed / --bg-wc-density | the matching attribute |
CSS
bg-wc { --bg-wc-color-1: hotpink; --bg-wc-color-bg: #0a0a0a; --bg-wc-intensity: 0.8;}The internal <canvas> is exposed as part="canvas" for further styling.
JavaScript API
Methods and properties on the element:
| Member | Behavior |
|---|---|
.preset | Reflects the preset attribute. |
.paused | Reflects the paused attribute. |
.pause() | Pauses the render loop. |
.resume() | Resumes the render loop. |
.snapshot() | Resolves to a PNG Blob of the current frame. |
.ready | Promise that resolves after the first frame renders. |
Events it dispatches:
| Event | Detail | When |
|---|---|---|
bg-wc:ready | { preset, renderer } | First frame rendered. |
bg-wc:preset-changed | { from, to } | After a successful preset swap. |
bg-wc:error | { phase, error } | Compile, load, or runtime error. |
bg-wc:visibility | { visible } | IntersectionObserver gate flips. |
Performance & reduced motion
- The render loop auto-pauses when the element scrolls off-screen (IntersectionObserver) and when the tab is hidden, so idle backgrounds cost nothing.
motion="auto"(the default) honorsprefers-reduced-motion: reduce.reduceforces a pause;forcealways animates.- When reduced motion is active and a preset has no static frame, the
fallbackslot is shown — supply a static image there for the best result.
Usage
HTML
<html data-theme="rough"> <body> <bg-wc preset="aurora" intensity="0.6" speed="0.8"> <header> <h1>Theme-aware hero</h1> <p>The aurora bands tint themselves from the active VB theme.</p> </header> <img slot="fallback" src="hero-static.webp" alt=""/> </bg-wc> </body></html>Custom properties declared on :root — which is exactly what VB themes do — inherit through the shadow boundary, so no piercing is required.