# Background Pattern
> A decorative, theme-aware pattern layer of dots, grid, lines, diagonal stripes or crosses for heroes, cards, empty states and auth screens.
- Type: React component (Text & Effects)
- Access: Pro (the source needs a Wingo UI Pro plan, see https://wingo-ui.com/pricing)
- Version: 1.0.0
- Install: `npx wingo-ui@latest add background-pattern`
- Docs: https://wingo-ui.com/components/background-pattern
## Interaction
Drop it into any positioned element and it fills the space behind the content with a fine SVG pattern that fades out toward the edges, in a faint foreground color that reads in light and dark mode. With animated on, a sparse set of cells pulses in and out at random, the same cells on the server and in the browser. With highlight set to pointer, a soft spotlight brightens the pattern under the mouse and fades away when it leaves; touch screens skip it. It never takes clicks or focus and is hidden from screen readers. Under prefers-reduced-motion the pulsing stops and the pattern stays still.
## Installation
```bash
npx wingo-ui@latest add background-pattern
```
Pro item: run `npx wingo-ui@latest login` once with a Pro account. The CLI adds the files, their dependencies and a version record for updates.
With shadcn: `npx shadcn@latest add @wingo-ui/background-pattern` (needs the @wingo-ui registry with your API key in components.json)
Files:
- `components/ui/background-pattern.tsx`
npm dependencies: `npm i motion`
Wingo UI dependencies (installed automatically):
- [Motion presets](https://wingo-ui.com/components/motion) ([Markdown](https://wingo-ui.com/components/motion.md))
- [Tones](https://wingo-ui.com/components/tones) ([Markdown](https://wingo-ui.com/components/tones.md))
- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))
## Usage
```tsx
import BackgroundPattern from "@/components/ui/background-pattern"
export function Hero() {
return (
Plan, build and ship in one place
)
}
```
## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `pattern?` | `"dots" \| "grid" \| "lines" \| "diagonal" \| "cross"` | `"dots"` | The drawing repeated across the surface. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Cell size: 16 / 24 / 40px. |
| `cellSize?` | `number` | `0` | An exact cell size in pixels that overrides size. 0 uses size. |
| `strokeWidth?` | `number` | `1` | Line width for grid, lines, diagonal and cross. |
| `dotSize?` | `number` | `1.5` | Dot radius for dots, capped at half the cell. |
| `tone?` | `"neutral" \| "brand" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | Semantic color. neutral is the foreground at 15% so it works in both themes; the other tones paint at 35% of the tone. |
| `color?` | `string` | `""` | Any CSS color; replaces the tone. The pattern paints at full strength in it, so pass a translucent color like rgb(124 58 237 / 0.3). |
| `fade?` | `"none" \| "radial" \| "top" \| "bottom" \| "edges"` | `"radial"` | Where the pattern fades out. radial keeps the middle, top keeps the top and fades downward, bottom the reverse, edges fades all four sides. |
| `animated?` | `boolean` | `false` | A sparse set of cells pulses in and out (dots, grid, lines and cross). The cells come from a fixed hash, so the server and the browser agree. Off under reduced motion and while scrolled out of view. |
| `density?` | `number` | `0.04` | Share of cells that pulse when animated, capped at about 160 cells at once. |
| `duration?` | `number` | `3000` | One pulse in milliseconds. Cells start at random points of the cycle. |
| `highlight?` | `"pointer" \| "none"` | `"none"` | pointer adds a soft spotlight that follows the mouse over the parent element. Fine pointers only, so phones and tablets never show it. |
| `position?` | `"absolute" \| "fixed" \| "static"` | `"absolute"` | absolute fills the nearest positioned parent behind its content (give the parent relative and isolate), fixed fills the viewport, static sits in the flow at the size you give it. |
| `classNames?` | `Partial>` | | Extra classes for the pattern svg, the fade mask wrapper and the spotlight layer. |
| `className?` | `string` | | Extra classes for the root, merged last. Change the strength with a text color, e.g. text-foreground/25. |
## Parts
### BackgroundPatternProps (type)
The props of BackgroundPattern: div props (without children and color) plus the options above.
### BackgroundPatternKind (type)
The pattern union: "dots" | "grid" | "lines" | "diagonal" | "cross".
### BackgroundPatternSize (type)
The size union: "sm" | "md" | "lg".
### BackgroundPatternFade (type)
The fade union: "none" | "radial" | "top" | "bottom" | "edges".
### BackgroundPatternHighlight (type)
The highlight union: "pointer" | "none".
### BackgroundPatternPosition (type)
The position union: "absolute" | "fixed" | "static".
### BackgroundPatternSlot (type)
The keys of classNames.
### BackgroundPatternTone (type)
The tone union, re-exported from lib/tones.
## Examples
- **Hero**: Dots with a radial fade behind a landing page headline.
- **Flickering grid behind a card**: animated lights up a few random cells; edges fades all four sides.
- **Auth layout**: Fine lines that fade out downward, behind a sign-in card.
- **Empty state**: Diagonal stripes give an empty screen some texture.
- **Brand tone with a spotlight**: tone brand and highlight pointer; the spotlight follows the mouse.
## See also
- [Hero Section](https://wingo-ui.com/components/hero-section) ([Markdown](https://wingo-ui.com/components/hero-section.md))
- [Empty State](https://wingo-ui.com/components/empty-state) ([Markdown](https://wingo-ui.com/components/empty-state.md))
- [Card](https://wingo-ui.com/components/card) ([Markdown](https://wingo-ui.com/components/card.md))
- [Login Page](https://wingo-ui.com/components/login-page) ([Markdown](https://wingo-ui.com/components/login-page.md))
- [Grid Reveal](https://wingo-ui.com/components/grid-reveal) ([Markdown](https://wingo-ui.com/components/grid-reveal.md))
---
Canonical: https://wingo-ui.com/components/background-pattern
More components: https://wingo-ui.com/components ยท Index for agents: https://wingo-ui.com/llms.txt