Background Pattern

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

This Pattern is part of Siteplane UI Pro, and its source comes with a Pro license. Its previews are free to view and try.

Installation

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

Usage

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

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

Composition

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.

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.

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.

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.

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.

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.

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.

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.

pnpm dlx shadcn@4.18.0 add @siteplane/card

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 list. The list renders in the dark theme on a light page as well.

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, behind a Metric Card and a prompt field on a card. rounded-[inherit] rounds the pattern with the outer card.

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 on a card.

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.

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

API reference

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.