---
title: Ambient background
description: Optional moving dither texture and a finite cursor wake, with the shared cursor colors and custom site colors.
sidebar:
  icon: waves
  order: 8
---

An optional background adapted from QorkMe. Add it where a moving texture suits the page; the [cursor](/cursor), [dropdowns](/dropdowns), and [paired footer](/footer-lockup) remain the standard site setup.

## Preview

<AmbientPreview />

Choose a palette and layout, or click a color chip to edit that color. Animate pauses or resumes the field.

<span id="add-it-to-a-page" />

## Install

The standalone script includes its styles and uses Canvas 2D. It needs no framework, images, videos, downloaded fonts, or other scripts. Mount it once after the body exists:

```html
<style>
  body { margin: 0; background: #F5F5F0; isolation: isolate; }
  .site-content { position: relative; z-index: 1; }
  main { min-height: 100vh; min-height: 100svh; width: 100%; }
</style>
<div class="site-content">
  <main><!-- Your page content and controls --></main>
  <footer><!-- Include the required paired-logo footer here. --></footer>
</div>
<script src="https://cdn.shaughv.com/js/shaughv-ambient.js?v=2026-10-21.2"></script>
<script>
  const ambient = ShaughvAmbient.mount({ color: "orange" });
</script>
```

The canvases are transparent and never intercept clicks or focus. Set your own page background and keep content above the decoration. Use solid control and panel surfaces where readability needs them. The default page layout leaves the middle reading column clear; its cursor wake remains visible across the viewport. The script does not install the shared cursor or alter your page's background, spacing, or content layout.

## Customize

### Colors and glyphs

Choose `orange`, `sage`, `black`, or `white` to match the cursor presets. `qork-ivory` retains QorkMe's original blue `#2663e1`, violet `#6f40e1`, and fallback dots `#5474d1`; pair it with a `#f6f4ef` page surface. Suggested surfaces are available in `ShaughvAmbient.palettes`, but are never applied automatically.

```js
const ambient = ShaughvAmbient.mount({
  color: "var(--site-accent)",
  secondary: "#8359c7", // Optional; a custom color otherwise uses one hue.
  glyphs: "STUDIO.",   // Default: QORK.ME; 1–64 characters.
});
ambient.setColor("sage");
ambient.setColor("#bd5429", "#8359c7");
```

Colors are resolved against the target's CSS when mounted or updated, outside the animation loop. Call `setColor()` again after changing a theme variable. Colors render in sRGB; changing the palette leaves density, timing, pointer physics, and transparency unchanged.

### A section or hero

Pass a positioned container to keep the effect inside one section. `layout: "stage"` uses the original elliptical field with 106 columns. `layout: "page"` uses the clear-center mask and adaptive grid, even inside a bounded container.

```html
<section id="hero" style="position:relative;isolation:isolate;min-height:360px">
  <div style="position:relative;z-index:1"><h1>Your work, in focus.</h1></div>
</section>
```

```js
const ambient = ShaughvAmbient.mount({
  target: document.querySelector("#hero"),
  layout: "stage",
  color: "qork-ivory",
});
```

The field fills the supplied container; size that container to frame the texture. Use `home: true` with the page layout for the original softer homepage intensity. At small viewport widths, the page mask widens its clear center and reduces intensity. A bounded section pauses while offscreen.

## Behavior

The original field motion, pointer displacement, and clear-center mask are preserved. Field ink is 40% stronger than the source for visibility on light surfaces; the wake is unchanged.

Reduced motion freezes the field and disables the wake. Touch keeps the ambient field, while the wake requires a fine mouse pointer and ignores dragging. Hidden tabs freeze the clock. Scroll, typing, blur, resizing, and tab hiding clear the wake; its last mark fades after 850 ms with no continuous wake animation afterward. Forced-colors mode hides the decoration. If Canvas is unavailable, static CSS dots remain and the page's controls keep working.

The page field paints at up to 24 fps; the stage and wake paint at up to 30 fps. Page and wake canvases each cap their backing size at approximately two million pixels and a pixel ratio of 1.25. The stage caps its pixel ratio at 1.5. These bounds do not guarantee a particular frame rate on every device.

<span id="controls-and-cleanup" />

## Lifecycle

```js
ambient.pause(true);   // Hold the field and clear the wake.
ambient.pause(false); // Resume if motion preferences and visibility allow it.
ambient.pulse();       // Send the original 1.4-second ring through the field.
ambient.destroy();     // Remove canvases, listeners, observers, and frame callbacks.
```

Load the script once in a framework, then mount in an effect and return `ambient.destroy` as its cleanup. A new mount on the same target replaces the old one; different section targets can have their own instances. If your framework removes a target, destroy its instance too. Do not create a new instance on every pointer event or render.

<span id="source-and-metadata" />

## Reference

The moving field, pointer displacement, pulse, and finite wake come from QorkMe. The Bayer/character treatment includes ObsidianUI's MIT attribution. Preserve the [Apache license](https://cdn.shaughv.com/brand/shaughv/ambient/LICENSE-APACHE-2.0.txt) and [source notices](https://cdn.shaughv.com/brand/shaughv/ambient/NOTICE.txt) when redistributing this component; those permissions do not cover other brand assets or fonts in the CDN.

Read `usage.components.ambient` in [the live catalog](https://cdn.shaughv.com/tree.json), or fetch [ambient-info.json](https://cdn.shaughv.com/brand/shaughv/ambient/ambient-info.json). This page is also exported as `/ambient-background.md`, `/ambient-background.mdx`, and `/api/docs/pages/ambient-background.json`.