# Background Pattern

Put a decorative grid, dot or line pattern behind a section or card.

Hero with cubes fading out from the center

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

```bash
pnpm dlx shadcn@4.18.0 add @siteplane-pro/background-pattern-demo
```

This Pattern is part of [Siteplane UI Pro](/pricing), and its source comes with a [Pro license](/docs/license/#patterns). Its previews are free to view and try.

## Installation

**Pro** — Installs with a Siteplane UI Pro license key. Complete the one-time [Pro setup](/docs/installation/#siteplane-ui-pro) first. Get a license on the [Pro page](/pricing).

```bash
pnpm dlx shadcn@4.18.0 add @siteplane-pro/background-pattern
```

With npm: `npx shadcn@4.18.0 add @siteplane-pro/background-pattern`.

## Usage

```tsx
import { BackgroundPattern } from "@/siteplane/components/background-pattern";

<BackgroundPattern
  pattern="grid"
  fade="radial"
  className="rounded-2xl px-8 py-16"
>
  …
</BackgroundPattern>;
```

## Composition

```text
BackgroundPattern
├── pattern layer (hidden from assistive technology)
│   ├── surface
│   ├── pattern with its fade
│   └── grain (optional)
└── children
```

`BackgroundPattern` is a box for your content. Its pattern layer fills the box behind the children, so the content needs no `z-index` and stays clickable. Without children it is a decorated box; to lay it behind other content, give it `absolute inset-0 -z-10` inside a parent with `relative isolate`.

## Patterns

There are nine patterns. `dots`, `grid`, `stripes`, `squares` and `lattice` repeat simple marks: dots, lines, rounded squares and 45° diamonds. `isometric`, `cubes` and `hexagons` share one isometric lattice and draw it as triangles, as cubes seen from above and as a honeycomb. `siteplane` draws the Siteplane UI mark on the same lattice: each mark nests between the two above it, and the slit of its S is a single line. Each pattern is a CSS mask, drawn by a gradient for `stripes` and by a small inline SVG tile for the others. No image file loads, and the pattern stays sharp on any screen.

All nine patterns

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

```bash
pnpm dlx shadcn@4.18.0 add @siteplane-pro/background-pattern-patterns-example
```

## Sizes

`size` sets the cell of the pattern: `sm`, `md` (the default) or `lg`. The cell is the spacing of the dots, stripes and squares, the square of the grid, the width of a lattice diamond, the column of the isometric lattice and the width of a Siteplane UI mark; a cube or a hexagon is two columns wide. Cells are fixed CSS pixels, so a pattern keeps its scale on every screen.

| Pattern             | `sm`  | `md`   | `lg`   |
| ------------------- | ----- | ------ | ------ |
| `dots`              | 12 px | 16 px  | 24 px  |
| `grid`              | 16 px | 24 px  | 48 px  |
| `stripes`           | 6 px  | 8 px   | 12 px  |
| `squares`           | 8 px  | 12 px  | 16 px  |
| `lattice`           | 48 px | 96 px  | 152 px |
| `isometric`         | 13 px | 26 px  | 52 px  |
| `cubes`, `hexagons` | 13 px | 26 px  | 39 px  |
| `siteplane`         | 72 px | 108 px | 160 px |

Cubes at sm, md and lg

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

```bash
pnpm dlx shadcn@4.18.0 add @siteplane-pro/background-pattern-sizes-example
```

## Fades

`fade` lets the pattern settle into the page instead of ending at a hard edge. `radial` fades it out from the center, `edges` along all four sides, and `top`, `bottom`, `start` and `end` toward the side they name. With `radial` the pattern is faint but not gone at the sides, so use it in a box with a visible edge, such as a card; `edges` clears all four sides. `start` and `end` follow the writing direction, so they mirror in right-to-left layouts.

Grid with each fade

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

```bash
pnpm dlx shadcn@4.18.0 add @siteplane-pro/background-pattern-fades-example
```

## Surfaces and tones

Without a surface the box is transparent and the pattern sits on the page. `surface` paints the box: `wash` is a soft accent gradient that clears toward the top, `accent` fills it with the accent color, and `dark` renders the box and its children in the dark theme, on a light page as well. `wash` and `accent` follow your theme's [accent color](/docs/customization/theming/#override-component-colors).

`tone` sets the color of the pattern. `neutral` uses the text color, `accent` the accent color and `contrast` white. It is `neutral` without a surface and `contrast` on one.

Neutral and accent tones, then the wash, accent and dark surfaces

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

```bash
pnpm dlx shadcn@4.18.0 add @siteplane-pro/background-pattern-surfaces-and-tones-example
```

## Line weight

`weight="regular"` draws lines and dots 1 px wide. `weight="hairline"` draws them half as wide on 2x and denser screens, which is one device pixel on a 2x display, and a little stronger, so the finer pattern does not fade. On standard screens it stays at 1 px, so compare the two on a high-density display. Filled `squares` look the same at both weights.

Isometric at 1 px and as a hairline

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

```bash
pnpm dlx shadcn@4.18.0 add @siteplane-pro/background-pattern-weight-example
```

## Grain

`grain` adds a fine noise over the box. On a surface, and on a dark page, it brightens the color in tiny specks, like film grain; on a light page without a surface it scatters faint dark specks instead.

Lattice on the accent without and with grain

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

```bash
pnpm dlx shadcn@4.18.0 add @siteplane-pro/background-pattern-grain-example
```

## Examples

### Stripes on a wash

`stripes` on `surface="wash"` with `fade="top"`, behind an install command and a release card.

Stripes on a wash behind an install command and a release card

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

```bash
pnpm dlx shadcn@4.18.0 add @siteplane-pro/background-pattern-stripes-wash-example
```

### Dots on a dark surface

`dots` on `surface="dark"`, behind a [Command](/docs/components/command/) list. The list renders in the dark theme on a light page as well.

Dots on a dark surface behind a command list

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

```bash
pnpm dlx shadcn@4.18.0 add @siteplane-pro/background-pattern-dots-dark-example
```

### Squares in a card

`squares` with `fade="start"` inside a subtle [Card](/docs/components/card/), behind a [Metric Card](/docs/patterns/metric-card/) and a prompt field on a card. `rounded-[inherit]` rounds the pattern with the outer card.

Squares fading in behind a metric card and a prompt field

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

```bash
pnpm dlx shadcn@4.18.0 add @siteplane-pro/background-pattern-squares-chart-example
```

### Lattice on the accent

A large `lattice` with `grain` on `surface="accent"`, behind a [Settings List](/docs/components/settings-list/) on a card.

Lattice with grain on the accent behind notification settings

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

```bash
pnpm dlx shadcn@4.18.0 add @siteplane-pro/background-pattern-lattice-accent-example
```

### The Siteplane UI mark on a wash

`siteplane` at `lg` on `surface="wash"`. `fade="top"` lets the marks fade out toward the top, where the wash turns light, so the heading sits on a clear background.

Siteplane UI marks on a wash behind a heading and two buttons

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

```bash
pnpm dlx shadcn@4.18.0 add @siteplane-pro/background-pattern-siteplane-example
```

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| pattern | dots \| grid \| stripes \| squares \| lattice \| isometric \| cubes \| hexagons \| siteplane | required | The pattern to draw. |
| size | sm \| md \| lg | md | Cell of the pattern: the spacing of dots, stripes and squares, the grid square, the diamond width, the isometric column or the width of a Siteplane UI mark. |
| fade | none \| radial \| edges \| top \| bottom \| start \| end | none | Fades the pattern out from the center, along all four sides or toward one side. start and end follow the writing direction. |
| surface | none \| wash \| accent \| dark | none | Paints the box behind the pattern. dark renders the box and its children in the dark theme. |
| tone | neutral \| accent \| contrast | neutral, or contrast on a surface | Color of the pattern: the text color, the accent color or white. |
| weight | regular \| hairline | regular | regular draws 1 px; hairline draws half as wide on 2x and denser screens. |
| grain | boolean | false | Adds a fine grain over the box. |
| className | string | unset | Layout of the box, such as its size, radius and padding. |
| children | ReactNode | unset | Content shown above the pattern. |

`BackgroundPatternProps` extends native div props, so `id`, `aria-*` and `ref` reach the box. `backgroundPatternNames` lists the nine pattern names, and the prop types are exported as `BackgroundPatternName`, `BackgroundPatternSize`, `BackgroundPatternFade`, `BackgroundPatternSurface`, `BackgroundPatternTone` and `BackgroundPatternWeight`.

## Usage notes

The pattern is decoration. Its layer is hidden from assistive technology and ignores the pointer, so it needs no text alternative and never blocks a click. Don't let a pattern carry meaning.

Keep text readable. Put patterns behind headings, cards and short copy rather than long text, and fade the pattern out where text sits on it. On the `accent` and `dark` surfaces keep the `contrast` tone; a neutral or accent pattern muddies the color.

Fields are translucent and take the color of what is behind them, so a pattern shows through them; put fields on a card, as in the squares example. On the `accent` surface, plain text turns white, but components that set their own text color keep it, so put them on a card as well.

`surface="dark"` switches its children to the dark theme. Siteplane UI components follow it; give your own content theme colors, such as `text-muted-foreground`, rather than fixed ones.

The box clips its content at its edges and rounded corners. Menus, popovers and tooltips open in a portal outside the box, so it does not clip them, and they keep the theme of the page.

The SVG tiles and the grain are `data:` URIs that CSS loads as images. If your Content Security Policy limits images through `img-src` or `default-src`, allow `data:` there; otherwise every pattern except `stripes` stays blank, and so does the grain.