Background Component

A polymorphic background renderer supporting dithering, mesh-gradient, WebGL pixel art, dotted-grid pattern, or no background — all theme-aware via next-themes.

BackgroundComponent is a single component that switches between five background modes via its type prop. Each mode accepts its own configuration props for colours and animation, plus shared colors / animation config objects for unified overrides.

The component listens to next-themes to provide sensible dark/light defaults automatically.

SSR note — This component uses WebGL/canvas. Load it with dynamic(() => import(...), { ssr: false }) where the WebGL type is used.

Installation

npx shadcn@latest add @adv/background-component

Usage

import dynamic from 'next/dynamic';

const BackgroundComponent = dynamic(
  () => import('@/components/BackgroundComponent').then(m => m.BackgroundComponent),
  { ssr: false }
);

// Dithering shader (default theme-aware colours)
<div className="relative h-screen">
  <BackgroundComponent type="dithering" />
</div>

// Mesh gradient with custom colours
<BackgroundComponent
  type="mesh-gradient"
  colors={['#e7fa7a', '#9a381d', '#f79850', '#d4704e']}
  speed={0.5}
/>

// Dotted grid pattern
<BackgroundComponent type="pattern" gridPattern="dark-white" />

Example

Props

All variants share className, style, and children.

`type="dithering"`

Prop	Type	Default	Description
`colorBack`	`string`	theme-aware	Background colour.
`colorFront`	`string`	theme-aware	Foreground/dither colour.
`shape`	`"warp" \| "circle" \| "square" \| "triangle"`	`"warp"`	Dither shape.
`ditherType`	`"4x4" \| "8x8" \| "16x16"`	`"8x8"`	Dither matrix size.
`pxSize`	`number`	`1.8`	Pixel size of dither pattern.
`speed`	`number`	`0.06`	Animation speed.
`scale`	`number`	`2.7`	Pattern scale.
`rotation`	`number`	`100`	Rotation angle.
`offsetX` / `offsetY`	`number`	`-0.14` / `-0.52`	Pattern offset.
`colors`	`ColorConfig`	—	Unified colour override.
`animation`	`AnimationConfig`	—	Unified animation override.

`type="mesh-gradient"`

Prop	Type	Default	Description
`colors`	`[string,string,string,string]`	theme-aware	Four gradient stop colours.
`distortion`	`number`	`0.8`	Distortion intensity.
`swirl`	`number`	`0.1`	Swirl strength.
`speed`	`number`	`1`	Animation speed.

`type="webgl"`

Prop	Type	Default	Description
`shape`	`"square" \| "circle" \| "triangle" \| "diamond"`	`"square"`	Pixel art shape.
`pixelSize`	`number`	`4`	Size of each pixel.
`ink`	`string`	`"#FFFFFF"`	Ink/foreground colour.
`interactive`	`boolean`	`true`	Enable mouse interaction.
`shapeScale`	`number`	`1.0`	Scale multiplier.

`type="pattern"`

Prop	Type	Default	Description
`gridPattern`	`GridPattern`	`"multi-layer"`	Preset: `multi-layer`, `dark-white`, `light-dark`, `minimal-white`, `minimal-dark`, `custom`.
`backgroundColor`	`string`	preset	Background fill.
`dotColors`	`[string,string,string]`	preset	Dot layer colours.
`dotSizes`	`[string,string,string]`	preset	Dot sizes.
`gridSizes`	`[string,string,string]`	preset	Background-size per layer.
`gridPositions`	`[string,string,string]`	preset	Background-position per layer.

`type="none"`

Renders nothing. Useful for conditional switching without unmounting the component.

Background Component

On this page