# BackgroundEffect

> A decorative canvas that fills a positioned region with one of seven pointer-reactive background effects, drawn in the current `--primary` colour.

## Facts

- **Product**: Crew OS
- **Family**: Appearance
- **Global**: `window.DigitalCrew.BackgroundEffect`
- **Source**: `digitalcrew-orchestrator: packages/ui/src/backgrounds.tsx`
- **Import in the app**: `import { BackgroundEffect } from "@/packages/ui/src/backgrounds";`
- **Live preview**: /design/components/background-effect/preview.html
- **Page**: /design/components/background-effect

## Guidelines

**Use it for** the personal workspace background a user picks in [`AppearanceControls`](/design/components/appearance-controls.md), and for its live preview. Always behind content, never behind dense tables.

**What you provide**: `kind` (from `BACKGROUND_OPTIONS`: `off`, `pixel-trail`, `neon-flow`, `interactive-gradient`, `halftone-trail`, `liquid`, `sonar-grid`, `kinetic-grid`), `intensity` (0 to 1, default 0.5; the appearance settings map low / medium / high to 0.25 / 0.5 / 0.8), `reducedMotion` (default false; the OS preference is always honoured too), `className`. Place it first inside a `relative`, `overflow-hidden` region; it is `position: absolute; inset: 0` and `pointer-events: none`. `off` renders nothing.

**Anatomy**: colour is read from the canvas's computed `color`, which is `var(--primary)`, and re-read when a class, style or `data-theme` changes on any ancestor. The canvas is capped at 1.5× device pixel ratio, 4096px per side and about 1.8 megapixels.

**Behaviour**: redraws at most 30 times a second, only while visible (IntersectionObserver, page visibility). Pointer moves over the parent feed trails and focal points; clicks that are not on controls add ripples. With reduced motion it draws one still frame and ignores the pointer; on touch screens it keeps animating but ignores touches; at intensity 0 it draws nothing. Every effect has an idle state that drifts on its own.

**Don't** stack two effects in one region, raise intensity behind text, or mount it outside a clipped, positioned parent.

## API

```ts
export { BACKGROUND_OPTIONS } from "./background-types.ts";
export type { BackgroundKind, BackgroundEffectProps } from "./background-types.ts";
/** Place inside a positioned, clipped region, behind its content. */
export declare function BackgroundEffect({ kind, intensity, reducedMotion, className }: BackgroundEffectProps): JSX.Element;
```

## Example

```html
<div id="root" class="p-6"></div>
<script>
(function () {
  var h = React.createElement, DC = window.DigitalCrew, I = DC.Icons;
  var kinds = DC.BACKGROUND_OPTIONS.filter(function (o) { return o.value !== "off"; });
  function App() {
    return h("div", { className: "grid grid-cols-4 gap-3" }, kinds.map(function (o) {
      return h("div", { key: o.value, className: "relative isolate h-52 overflow-hidden rounded-xl border bg-background" },
        h(DC.BackgroundEffect, { kind: o.value, intensity: 0.8 }),
        h("div", { className: "absolute inset-x-0 bottom-0 grid gap-0.5 bg-background/80 p-2.5" },
          h("span", { className: "text-xs font-medium" }, o.label),
          h("span", { className: "text-muted-foreground text-[11px] leading-snug" }, o.description)));
    }));
  }
  ReactDOM.createRoot(document.getElementById("root")).render(h(DC.TooltipProvider, { delayDuration: 80 }, h(App)));
})();
</script>
```

## More in Appearance

- [AppearanceControls](/design/components/appearance-controls.md): The "Appearance" settings panel from `@digitalcrew/ui`: density, button finish, motion, background effect and intensity, the splash cursor, and a live preview of the result.