Rainbow hue cycle on --rainbow-hue. Use the web component, a CSS class, or applyRainbow().

Install

npm install nui-rainbow

Web component

<script type="module">
  import 'nui-rainbow';
</script>

<nui-rainbow duration="12s">
  <h1>Hue lives on --rainbow-hue</h1>
</nui-rainbow>

h1 {
  color: hsl(var(--rainbow-hue) 55% 52%);
}

Or use a ready-made token:

h1 {
  color: var(--nui-rainbow-color);
  background: var(--nui-rainbow-color-soft);
  border-color: var(--nui-rainbow-complement);
}

Vue:

<nui-rainbow :duration="speed" :paused="paused" initial-hue="210deg">
  <slot />
</nui-rainbow>

Props / attributes

| Prop | Attribute | Default | Notes | |---|---|---|---| | duration | duration | 30s | Number = seconds (12 → 12s). Also 800ms. | | initialHue | initial-hue | 132deg | Cycle origin. Alias: from. | | from | from | 132deg | Same as initialHue. Wins when both are set. | | to | to | origin + 360deg | Sets span to to - from. | | hueSpan | hue-span | 360deg | How far the cycle travels. Ignored when to is set. | | offset | offset | 0deg | Extra hue shift (stagger children). | | easing | easing | linear | Any CSS easing. | | iterations | iterations | infinite | Number or infinite. | | delay | delay | 0s | Number = seconds. | | paused | paused | false | Boolean attribute. | | direction | direction | normal | normal / reverse / alternate / alternate-reverse. | | fillMode | fill-mode | none | none / forwards / backwards / both. | | cycle | cycle | branded | branded (curved path) or linear (even 360°). | | reducedMotion | reduced-motion | reduce | ignore keeps motion when the user prefers reduced motion. | | saturation | saturation | 55% | Used by color tokens. Number = percent. | | lightness | lightness | 52% | Used by color tokens. Number = percent. | | alpha | alpha | 1 | Used by color tokens. |

<nui-rainbow> emits rainbowcycle on each animation iteration (detail.animationName).

Class or helper

import { applyRainbow } from 'nui-rainbow';

const stop = applyRainbow(document.querySelector('.surface'), {
  duration: 45,
  paused: false,
  cycle: 'linear',
  offset: 24,
});

el.addEventListener('rainbowcycle', () => { /* next lap */ });

stop();

<div class="nui-rainbow" style="--nui-rainbow-duration: 12s">
  …
</div>

@import 'nui-rainbow/styles.css';

.surface {
  color: hsl(var(--rainbow-hue) 55% 52%);
}

.nuc-rainbow is an alias of .nui-rainbow.

CSS-only usage does not emit rainbowcycle. Call bindRainbowCycle(el) if you need the event without applyRainbow().

Recipes

Add a recipe class on the cycling element or a descendant (--rainbow-hue inherits):

| Class | Effect | |---|---| | .nui-rainbow-text | Rainbow gradient clipped to text. | | .nui-rainbow-border | Border tinted with --nui-rainbow-color. | | .nui-rainbow-underline | Underline tinted with --nui-rainbow-color. |

.nuc-rainbow-text, .nuc-rainbow-border, and .nuc-rainbow-underline are aliases.

<nui-rainbow class="nui-rainbow-text">Hello</nui-rainbow>

--rainbow-hue inherits, so a child can add its own shift:

.letter {
  color: hsl(
    calc(var(--rainbow-hue) + var(--nui-rainbow-offset, 0deg))
      var(--nui-rainbow-saturation) var(--nui-rainbow-lightness)
  );
}

<div class="nui-rainbow">
  <span style="--nui-rainbow-offset: 0deg">A</span>
  <span style="--nui-rainbow-offset: 24deg">B</span>
  <span style="--nui-rainbow-offset: 48deg">C</span>
</div>

Or put .nui-rainbow on each letter with a different --nui-rainbow-offset so tokens like --nui-rainbow-color pick up the shift.

Compose with another animation

The cycle lives on --nui-rainbow-animation. Keep another animation without overwriting it:

.surface {
  --nui-rainbow-extra-animation: fade-in 0.4s ease;
}

Or list it yourself:

.surface {
  animation: fade-in 0.4s ease, var(--nui-rainbow-animation);
}

CSS variables

Set these on the same element that has the class / component:

| Variable | Role | |---|---| | --rainbow-hue | Public hue token for hsl() / oklch(). | | --nui-rainbow-color | hsl(hue saturation lightness / alpha). | | --nui-rainbow-color-soft | Lighter, less saturated sibling. | | --nui-rainbow-color-muted | Duller sibling. | | --nui-rainbow-complement | Opposite hue, same S/L/alpha. | | --nui-rainbow-complement-hue | --rainbow-hue + 180deg. | | --nui-rainbow-oklch | Same cycle in oklch(). | | --nui-rainbow-duration | Cycle length. | | --nui-rainbow-initial-hue | Cycle origin. | | --nui-rainbow-from | Hue at progress 0 (defaults to initial hue). | | --nui-rainbow-to | Computed from + span. | | --nui-rainbow-span | Travel distance (default 360deg). | | --nui-rainbow-offset | Extra hue shift. | | --nui-rainbow-easing | Timing function. | | --nui-rainbow-iterations | Repeat count. | | --nui-rainbow-delay | Start delay. | | --nui-rainbow-direction | Animation direction. | | --nui-rainbow-fill-mode | animation-fill-mode. | | --nui-rainbow-saturation | For color tokens. | | --nui-rainbow-lightness | For color tokens. | | --nui-rainbow-alpha | For color tokens. | | --nui-rainbow-animation | Full cycle shorthand. | | --nui-rainbow-extra-animation | Optional extra animation to compose. |

prefers-reduced-motion: reduce stops the animation unless reduced-motion="ignore".

Styles

applyRainbow() / <nui-rainbow> adopt a constructable stylesheet when the document supports it, and fall back to a <style id="nui-rainbow-styles"> tag. For a shadow root:

import { getRainbowStyleSheet } from 'nui-rainbow';

shadow.adoptedStyleSheets = [...shadow.adoptedStyleSheets, getRainbowStyleSheet()];