Documentation

Install the package. React ≥ 18 is a peer dependency.

npm i ethereal-glow

Or, if you use shadcn/ui, take the registry path instead — it drops an EtherealButton into components/ui/ that you own and can restyle, with ethereal-glow added as a dependency so fixes still arrive over npm rather than being stranded in your tree.

npx shadcn@latest add https://ethereal.ale.design/r/ethereal.json

Drop an effect inside any element that is a positioned, isolated host — position: relative plus isolation: isolate. Keep your own content on a higher stacking layer (relative z-10) so it sits above the glow.

import { Ethereal, EventHorizon } from 'ethereal-glow'

// Ethereal — a comet travels the border behind a spotlight mask
<button className="relative isolate ...">
  <span className="relative z-10">Get started</span>
  <Ethereal path="around" heads={2} spin="counter" />
</button>

// EventHorizon — a black-hole accretion disk
<button className="relative isolate ...">
  <span className="relative z-10">Enter</span>
  <EventHorizon />
</button>

A comet head travels along the element behind a spotlight mask: a lit stretch of the border ring, an interior color wash, thin light needles and a white-hot core. Every prop is an optional override of the exported ETHEREAL defaults.

<Ethereal> and <EtherealWrap> accept a state prop — a named partial config merged over your base props. Change it and the rebuilt layers cross-fade. The two built-ins are exported as ETHEREAL_STATES.

Light and dark can also want different values, not just a dimmer version of the same glow — branch the base config with themes. It sits below states on purpose: a state is the more specific thing, so a named state can still override the theme baseline. The full merge order, lowest to highest:

themes is the only per-theme mechanism — all three effects take it, and it is the whole light-mode story for each of them. “Same config, just dimmer on white” is themes={{ light: { strength: 0.6 } }}.

import { Ethereal, ETHEREAL_STATES } from 'ethereal-glow'

// Switch named states — the rebuilt layers cross-fade over transitionMs.
// Built-ins: 'idle' | 'thinking'.
<button className="relative isolate ...">
  <span className="relative z-10">Send</span>
  <Ethereal state={status} />
</button>

// A state is keyed by VARIANT, not by config key directly:
//   light / dark        the theme branch, picked by the resolved theme
//   .base               that theme's config for the state
//   .whileHover         merged on top while hovered (mouse only)
//   .whilePressed       merged on top while pressed — pointer OR keyboard,
//                       held ~600ms so quick clicks stay visible
// Theme owns interaction, so light and dark can carry different hover treatments.
// Later variants win, so whilePressed can override whileHover.
// Custom states merge over the built-ins per variant; unknown names warn
// once and fall back to the base config.
<Ethereal
  state="sending"
  states={{
    sending: {
      light: {
        base: { colors: ['#3b82f6'], duration: 1.2 },
        whileHover: { strength: 1.4 },
      },
      dark: {
        base: { colors: ['#7ab8ff'], duration: 1.2 },
        whileHover: { strength: 1.8 },
      },
    },
  }}
  transitionMs={200} // 0 disables the cross-fade
/>

Tuning this in the playground

The playground edits the same cascade this page describes, one cell at a time. The Base row is the flat config every state inherits; each named state below it is a states entry. Inside a row, the two pill strips pick which cell you are editing: theme, then interaction slot.

On the Base row the theme pills read base and dark ↑ rather than light/dark, because the base config is not symmetric: base edits the shared flat props, and dark ↑ writes a themes.dark override on top — the same shape as Tailwind’s base styles plus dark: variants. On a named state the pills are plain light / dark, because a state really does have two symmetric branches.

A green dot on a pill means that cell holds overrides; an amber dot beside a control means this cell sets it — click it to clear. Whichever control section you have expanded stays expanded as you switch theme, slot or state, so you can compare one group of values across cells without losing your place.

A black-hole accretion disk: a white-hot head orbits, trailing a doppler-tinted plasma stream, wrapped in a graduated gravitational lens, a living photon rim and a lensed halo. Overrides the exported EVENT_HORIZON defaults.

EVENT_HORIZON_PRESETS

Five ready-made configs, spread straight onto the component.

import { EventHorizon, EVENT_HORIZON_PRESETS } from 'ethereal-glow'

<EventHorizon {...EVENT_HORIZON_PRESETS['Violet quasar']} />

State, theme & interaction props

Identical to Ethereal's, with EventHorizonCfg as Cfg — state, states, themes, whileHover, whilePressed and the theme props all resolve through the same shared implementation. Built-in states: EVENT_HORIZON_STATES.

The same travelling comet, rendered as ordered-dithered blocks on a canvas instead of CSS gradients — a Bayer-quantized palette that reads as pixel art. It is the one effect that repaints every tick rather than writing CSS variables, so consider setTickRate(30) when you use it. Overrides the exported ETHEREAL_DITHER defaults.

State, theme & interaction props

Identical to Ethereal's, with EtherealDitherCfg as Cfg. Built-in states: ETHEREAL_DITHER_STATES.

<EtherealWrap>, <EventHorizonWrap> and <EtherealDitherWrap> render the positioned, isolated host span for you and place the effect inside it, with your children on a raised layer. Use them when you can't edit the child — third-party components, or replaced elements like <input> and <textarea>, which can't contain the effect span at all.

They accept every config prop, plus className and style on the wrapper. The glow follows the wrapper's border radius, so match it to the child (e.g. give children rounded-[inherit]).

import { EtherealWrap, EventHorizonWrap, EtherealDitherWrap } from 'ethereal-glow'

// Replaced elements (inputs, textareas) can't contain the effect span —
// wrap them instead. The wrapper span becomes the positioned, isolated host.
<EtherealWrap path="static">
  <SearchInput />
</EtherealWrap>

// EventHorizonWrap and EtherealDitherWrap provide the same host contract.

• One shared ticker. A single requestAnimationFrame loop, targeting ~60fps — one tick per frame on a 60Hz display; higher-refresh displays are gated down to the target — drives every instance of all three effects; it stops entirely when the last instance unmounts. Off-screen instances pause via an IntersectionObserver (160px margin), and the loop clamps dt after background-tab pauses so clocks never jump.
• Tunable frame rate. setTickRate(fps) changes the shared loop’s target — 0 ticks at the display’s native refresh rate, 30 halves the paint cost for hero-size effects. Animation speed is unaffected either way, since every effect integrates against wall-clock dt rather than counting frames.
• No layout thrash. Layout metrics are cached by a ResizeObserver and refreshed only on real size changes — the per-frame code only writes CSS custom properties, never reads offsetWidth/offsetHeight.
• Reduced motion. Under prefers-reduced-motion: reduce a single static glow frame renders with no animation loop.
• Host requirements. The parent must be position: relative + isolation: isolate. A position: static host is warned about in the console (the glow would anchor to the wrong ancestor).
• One effect per host. Mounting two effects (or two of the same) on the same element makes them fight over the shared CSS variables; the second logs a console warning. Give each effect its own host.
• State transitions. Re-render with a different config and the rebuilt layers cross-fade in over ~320ms — e.g. idle → thinking on a chat composer.
• Theming. The effect honors html[data-theme], .light/.dark classes, or the OS scheme, so Tailwind's class strategy, shadcn/ui and next-themes all work unconfigured; theme pins it and themeDetector replaces the chain. One document-wide observer and one matchMedia listener serve every mounted instance, so a theme toggle updates the glow live no matter how many are on the page (use themes.light to tune any of the three effects for light backgrounds).

/* Every effect needs a positioned, isolated host. Tailwind: */
<button className="relative isolate ..."> … </button>

/* Plain CSS: */
.host { position: relative; isolation: isolate; }