Background Pattern React component for Tailwind CSS v4
v1.0.0Added in 1.10.0
A decorative, theme-aware pattern layer of dots, grid, lines, diagonal stripes or crosses for heroes, cards, empty states and auth screens.
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.
Background Pattern is a Pro React component in the React effect components category, written in TypeScript for React 19 and Tailwind CSS v4. It installs as source with npx wingo-ui@latest add background-pattern, together with Motion presets, Tones and UIProvider and the npm package motion.
Add to a project
Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup
npx wingo-ui@latest add background-patternPro item: the CLI needs a Pro account. See plans
Usage
Import BackgroundPattern from @/components/ui/background-pattern.
import BackgroundPattern from "@/components/ui/background-pattern"
export function Hero() {
return (
<section className="relative isolate overflow-hidden px-6 py-24 text-center">
<BackgroundPattern pattern="dots" fade="radial" />
<h1 className="text-4xl font-semibold tracking-tight">Plan, build and ship in one place</h1>
</section>
)
}Props
patterndefault"dots""dots" | "grid" | "lines" | "diagonal" | "cross"The drawing repeated across the surface.
sizedefault"md""sm" | "md" | "lg"Cell size: 16 / 24 / 40px.
cellSizedefault0numberAn exact cell size in pixels that overrides size. 0 uses size.
strokeWidthdefault1numberLine width for grid, lines, diagonal and cross.
dotSizedefault1.5numberDot radius for dots, capped at half the cell.
tonedefault"neutral""neutral" | "brand" | "success" | "warning" | "danger" | "info"Semantic color. neutral is the foreground at 15% so it works in both themes; the other tones paint at 35% of the tone.
colordefault""stringAny 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).
fadedefault"radial""none" | "radial" | "top" | "bottom" | "edges"Where the pattern fades out. radial keeps the middle, top keeps the top and fades downward, bottom the reverse, edges fades all four sides.
animateddefaultfalsebooleanA 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.
densitydefault0.04numberShare of cells that pulse when animated, capped at about 160 cells at once.
durationdefault3000numberOne pulse in milliseconds. Cells start at random points of the cycle.
highlightdefault"none""pointer" | "none"pointer adds a soft spotlight that follows the mouse over the parent element. Fine pointers only, so phones and tablets never show it.
positiondefault"absolute""absolute" | "fixed" | "static"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.
classNamesPartial<Record<"svg" | "mask" | "highlight", string>>Extra classes for the pattern svg, the fade mask wrapper and the spotlight layer.
classNamestringExtra classes for the root, merged last. Change the strength with a text color, e.g. text-foreground/25.
Parts
BackgroundPatternProps
typeThe props of BackgroundPattern: div props (without children and color) plus the options above.
BackgroundPatternKind
typeThe pattern union: "dots" | "grid" | "lines" | "diagonal" | "cross".
BackgroundPatternSize
typeThe size union: "sm" | "md" | "lg".
BackgroundPatternFade
typeThe fade union: "none" | "radial" | "top" | "bottom" | "edges".
BackgroundPatternHighlight
typeThe highlight union: "pointer" | "none".
BackgroundPatternPosition
typeThe position union: "absolute" | "fixed" | "static".
BackgroundPatternSlot
typeThe keys of classNames.
BackgroundPatternTone
typeThe 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.
Files
- components/ui/background-pattern.tsx
FAQ
Is the React Background Pattern component free?
The preview, props and docs are free; copying the source needs a Pro plan. See plans.
How do I install Background Pattern?
Run npx wingo-ui@latest add background-pattern. It also adds the Wingo UI items it builds on (Motion presets, Tones and UIProvider) and the npm package motion. With shadcn, add the @wingo-ui registry with your API key, then run npx shadcn@latest add @wingo-ui/background-pattern.