---
title: "Background Gradient"
description: "Animated canvas background gradient with theme variants"
source: "Equality"
---
import { BgGradientDemo } from "@demo/components/demo/bg-gradient";

## Overview

The Background Gradient renders a slowly animating field of soft, blurred color blobs onto a full-viewport `<canvas>`. It is intended as a decorative backdrop for hero sections, landing pages, and empty states, sitting behind foreground content.

## Usage

Import the component:

```tsx
import { BgGradient } from "@eqtylab/equality";
```

Basic usage. `theme` is required; `placement` defaults to `"full"`. Wrap it in a positioned, sized container so the canvas has room to fill:

```tsx
<div className="relative h-150 w-full *:size-full">
  <BgGradient theme="primary" />
</div>
```

## Theme Variants

Set the `theme` prop to any brand color key to recolor the gradient.

### Primary

<BgGradientDemo client:load variant="primary" />

### Secondary

<BgGradientDemo client:load variant="secondary" />

### Green

<BgGradientDemo client:load variant="green" />

### Red

<BgGradientDemo client:load variant="red" />

### Yellow

<BgGradientDemo client:load variant="yellow" />

### Usage

```tsx
<BgGradient theme="primary" />
<BgGradient theme="secondary" />
<BgGradient theme="green" />
<BgGradient theme="red" />
<BgGradient theme="yellow" />
```

## Placement Variants

Use the `placement` prop to control where the blobs are distributed. `"full"` (the default) scatters four blobs around all four corners, while `"top"` uses two blobs anchored near the top edge for a subtler decoration that leaves the lower area clear for content.

### Placement Full

<BgGradientDemo client:load placement="full" />

### Placement Top

<BgGradientDemo client:load placement="top" />

### Usage

```tsx
<BgGradient theme="primary" placement="full" />
<BgGradient theme="primary" placement="top" />
```

## Props

| Name        | Description                                                                                                   | Type                                             | Default | Required |
| ----------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ------- | -------- |
| `theme`     | Brand color used for the gradient blobs. Read from `equality-tokens.json`; unknown values fall back to black. | `primary`, `secondary`, `green`, `red`, `yellow` | —       | ✅       |
| `placement` | Distribution of the gradient blobs. `full` covers the whole area; `top` anchors blobs near the top edge.      | `full`, `top`                                    | `full`  | ❌       |