Aurora Gradient Field

Quick Start

1. Add to your HTML <head>:

Code snippet omitted: it ships with the download.

2. Add the field to your <body>:

Code snippet omitted: it ships with the download.

3. Add before the closing </body> tag:

Code snippet omitted: it ships with the download.

The script finds every [data-aurora] element, writes custom properties onto it and its layers on a shared ticker, drives the bloom with gsap.quickTo, and stops entirely when the field scrolls off screen or the tab is hidden. It needs no GSAP plugins.

Pointer tracking is bound to window, not to the field. This is deliberate and it is what makes the effect usable as a page background: if the listener sat on the element, every paragraph, link and button stacked on top of the field would swallow the movement and the light would only follow the cursor over the gaps between your content.

Using It With Your Own Design

The effect never looks at a class name. It needs four things from your markup:

1. A positioning context on the field. [data-aurora] is position: relative; overflow: hidden; isolation: isolate. The isolation matters: layer two and the sweep blend with mix-blend-mode: screen, and without an isolated stacking context they would blend with whatever sits behind the field on your page.
2. At least one [data-aurora-layer]. Layers are position: absolute; inset: -24%. That overscan is deliberate: the layers translate toward the pointer, and at inset: 0 you would see their edges arrive. Two layers is the tuned arrangement; one is calmer and cheaper, three or more starts to mud.
3. Your content above the field. The layers are all pointer-events: none, but they are still painted after nothing in particular, so give your content wrapper position: relative; z-index: 2.
4. A palette. Either use one of the four included, or copy a palette block in style.css and change the six hue numbers. Nothing in the JavaScript knows the palette names.

[data-aurora-sweep], [data-aurora-focus], [data-aurora-echo], [data-aurora-grain], [data-aurora-scrim] and [data-aurora-readband] are all optional, but they each do a job:

• The sweep is the wide conic band that turns behind the stops. Without it the field is a pleasant wash that never quite reads as aurora. Its cone origin sits outside the element on purpose; move it inside and its apex shows as a hard convergence point in the middle of your hero.
• The bloom and echo are the paired light that follows the pointer. The compact bloom arrives at data-aurora-follow; the wider echo uses 1.9 times that delay, leaving a soft wake on decisive pointer moves. Both are parked dead centre by CSS (left: 50%; top: 50% with negative margins) and the script drives them as offsets from there, so the resting position is correct before any script runs and stays correct without JavaScript. Do not re-anchor them to the top-left and centre them from JavaScript: they then paint in the corner for one frame on load, which is a visible flash.
• The grain is a small SVG noise tile at 14% opacity. Large gradients band visibly on 8-bit displays, and this is the difference between smooth and stripey on a real monitor. It is the first thing to delete if you are compositing over your own texture.
• The scrim is a light, whole-surface veil that seats the colour on a dark page. It takes roughly a sixth off the field and no more. It is not the contrast treatment, and turning it up until your body copy is readable is the mistake this effect used to ship with: it costs you the whole field to protect the fraction of it that has text on it.
• The readband is the contrast treatment, and it is local. A band of shade the width of your reading column, feathered to fully transparent on both sides so there is no edge to see, running the full height of the field. Text sits in the shaded core and the field runs at full strength in the margins. Its opacity is held flat, so the column's contrast ratio never drifts.

Putting text over the field

Set --a-read on the readband to your own measure and leave everything else alone:

Code snippet omitted: it ships with the download.

--a-read is the flat, fully shaded core; the feather (--a-read-feather, 9rem) is added outside it, so the element is wider than the number you set. That is the intent: the shade has to be at full strength across the whole measure and reach nothing at all before the page edge.

Text that runs wider than the reading column needs its own patch, because the band deliberately does not reach it. A masthead row, a footer, a full-bleed caption: give it a feathered pseudo-element of its own rather than widening the band. The one thing to get right is where the feather sits: put every gradient stop at the same length as the corresponding negative inset, so the patch is at full strength across the whole block and fades only in the overhang. Feather in percentages instead and the ends of a wide row sit in the falloff, which on most pages is exactly where the smallest type is.

Everything in style.css from the .stage rule down is the demo's own layout and can be deleted. The one rule worth keeping from it: the field is position: fixed; inset: 0; z-index: 0 and your content is position: relative; z-index: 1. That is what makes this a background rather than a box.

Options

Set these on the [data-aurora] element.

Child hooks:

Custom Properties

The script writes these onto the field; the CSS declares a composed resting value for each, which is what you see before the script runs and what a visitor without JavaScript keeps.

Only --a-hue-shift moves while the field runs; the light values are written every pass but held flat. That is what lets the readband be tuned once and stay correct: a background whose brightness swings has to be measured for contrast at its peak as well as at rest, and the peak is always the one that gets forgotten.

Accessibility

• Reduced motion: under prefers-reduced-motion: reduce the script paints one composed frame and attaches no ticker or pointer listeners. Palette buttons remain operable and change the still instantly, without the cross-fade dip.
• Without JavaScript: the CSS carries a complete resting state, so the field paints in full. Nothing on the page is hidden waiting for a script.
• Contrast: the field's light values are held flat, so the reading band can be tuned once. Measured per real glyph pixel across all four palettes, white copy over the field stays at or above 5.9:1, comfortably past the 4.5:1 AA threshold. Text that runs outside the band needs its own patch; see "Putting text over the field" above.
• Keyboard: the palette controls are ordinary buttons carrying aria-pressed, so the only interactive part of the effect is reachable and announced.
• Touch: a coarse pointer has no hover, so a tap or a drag places the bloom where the finger landed.
• Decorative by definition: every layer carries aria-hidden="true" and pointer-events: none. Nothing the effect adds is announced or focusable.

Performance

• Transforms are set every frame; the gradient properties, which repaint the whole field, are written at about 24fps. At this drift rate the difference is invisible and it roughly halves the paint cost.
• An IntersectionObserver removes the ticker when the field leaves the viewport, and a visibilitychange listener removes it in a hidden tab.
• Prefer one field per page. Several large gradient fields painting at once is the one way to make this expensive.

Dependencies

• GSAP 3.15.0 (core only, no plugins)

Browser Support

Uses modern hsl() slash-alpha syntax, conic-gradient, mix-blend-mode and background-blend-mode: current Chrome, Safari, Firefox and Edge. Older engines fall back to the field's base colour, which is a solid dark ground rather than a broken layout.