Background Pattern

A decorative pattern behind your content, with an optional cursor-following spotlight.

Move your cursor over the panel

Usage

import { BackgroundPattern } from '@appica/ui-react/background-pattern'

<BackgroundPattern>
  <YourContent />
</BackgroundPattern>

BackgroundPattern is a <div> wrapper that paints a subtle, masked pattern behind its children. Pick a texture with the variant prop (dots by default, grid, hexagons, rings or checkerboard) and tune its density with cellSize. The pattern is drawn from the --pattern-color CSS variable (defaulting to the --color-border-intense token) via currentColor masks, so it stays muted against either light or dark surfaces; override that variable to recolor it.

Enable spotlight to add a radial highlight that follows the cursor and brightens the pattern nearby; pass true for the default, a number/length to size it, or { persistent: true } to keep it always on. The decorative layers are aria-hidden, so they never interfere with assistive tech - your children remain fully accessible, and the wrapper accepts className, style, and any native <div> attributes.

Examples

Variants

5 textures cover the common cases: scattered dots, a grid with a dot at every intersection, a hexagons mesh, staggered rings and a checkerboard. Each carries a sensible default cell size, drawn at low opacity so content stays legible. For the checkerboard, cellSize sets the size of one square.

dots

grid

hexagons

rings

checkerboard

import { BackgroundPattern } from '@appica/ui-react/background-pattern'

const variants = ['dots', 'grid', 'hexagons', 'rings', 'checkerboard'] as const

export default function BackgroundPatternVariants() {
  return (
    <div className="grid w-full max-w-2xl grid-cols-1 gap-4 sm:grid-cols-2">
      {variants.map((variant) => (
        <BackgroundPattern
          key={variant}
          variant={variant}
          className="bg-background-subtle flex min-h-40 items-center justify-center overflow-hidden rounded-xl sm:last:col-span-2"
        >
          <span className="text-foreground-intense text-sm font-medium capitalize">{variant}</span>
        </BackgroundPattern>
      ))}
    </div>
  )
}

Spotlight

Set spotlight to add a cursor-following highlight that brightens the pattern near the pointer and fades out when the cursor stops. Move your cursor over the panel to see it react.

Move your cursor over the panel

import { BackgroundPattern } from '@appica/ui-react/background-pattern'

export default function BackgroundPatternSpotlight() {
  return (
    <BackgroundPattern
      variant="dots"
      spotlight
      className="bg-background-subtle flex min-h-56 w-full max-w-xl items-center justify-center overflow-hidden rounded-xl"
    >
      <span className="text-foreground-intense text-sm font-medium">Move your cursor over the panel</span>
    </BackgroundPattern>
  )
}

Persistent / sized spotlight

Pass an object to keep the highlight always on with { persistent: true } and size it with size (a number in px, or any CSS length). A persistent spotlight skips the fade entirely.

Always-on highlight

import { BackgroundPattern } from '@appica/ui-react/background-pattern'

export default function BackgroundPatternPersistentSpotlight() {
  return (
    <BackgroundPattern
      variant="rings"
      spotlight={{ persistent: true, size: 150 }}
      className="bg-background-subtle flex min-h-56 w-full max-w-xl items-center justify-center overflow-hidden rounded-xl"
    >
      <span className="text-foreground-intense text-sm font-medium">Always-on highlight</span>
    </BackgroundPattern>
  )
}

Custom cell size

cellSize overrides the per-variant default to make the texture denser or airier. The grid and rings strokes stay the same width at any size, so only the spacing changes. Here the same grid variant is shown at 2 scales.

cellSize 16

cellSize 40

import { BackgroundPattern } from '@appica/ui-react/background-pattern'

export default function BackgroundPatternCellSize() {
  return (
    <div className="grid w-full max-w-2xl grid-cols-1 gap-4 sm:grid-cols-2">
      <BackgroundPattern
        variant="grid"
        cellSize={16}
        className="bg-background-subtle flex min-h-48 items-center justify-center overflow-hidden rounded-xl"
      >
        <span className="text-foreground-intense text-sm font-medium">cellSize 16</span>
      </BackgroundPattern>
      <BackgroundPattern
        variant="grid"
        cellSize={40}
        className="bg-background-subtle flex min-h-48 items-center justify-center overflow-hidden rounded-xl"
      >
        <span className="text-foreground-intense text-sm font-medium">cellSize 40</span>
      </BackgroundPattern>
    </div>
  )
}

Custom color

The pattern reads its color from the --pattern-color CSS variable, which defaults to the muted --color-border-intense token. Set it to recolor the texture - point it at a theme token like var(--primary), or drop in any custom value. Here a bluish-purple hex tints the pattern and its spotlight, paired with a matching surface mixed from the same hue and var(--background) via color-mix, so the wash stays subtle in both light and dark mode.

Tinted with a custom color

import { BackgroundPattern } from '@appica/ui-react/background-pattern'

export default function BackgroundPatternCustomColor() {
  return (
    <BackgroundPattern
      variant="hexagons"
      spotlight
      className="flex min-h-56 w-full max-w-xl items-center justify-center overflow-hidden rounded-xl bg-[color-mix(in_oklab,#7c6cf6_8%,var(--background))] [--pattern-color:#7c6cf6]"
    >
      <span className="text-foreground-intense text-sm font-medium">Tinted with a custom color</span>
    </BackgroundPattern>
  )
}

API reference

Prop	Type	Default	Description
`variant`	`'dots' \| 'grid' \| 'hexagons' \| 'rings' \| 'checkerboard'`	`'dots'`	Pattern texture painted behind the content.
`spotlight`	`boolean \| number \| string \| { size?, persistent? }`	`false`	Cursor-following highlight. `true` for a 200px fading highlight; a number/length sizes it; an object with `persistent: true` keeps it always on.
`cellSize`	`number`	-	Cell size in px; overrides the per-variant default (dots 14, grid 28, hexagons 40, rings 48; checkerboard 16, per square).
`track`	`'self' \| 'window'`	`'self'`	Where the spotlight reads pointer movement. `'self'` tracks over this element; `'window'` tracks anywhere - for a pattern positioned behind unrelated content.
`className`	`string`	-	Extra classes, merged via `tailwind-merge`.
`style`	`CSSProperties`	-	Inline styles on the wrapper.

BackgroundPattern renders a <div> and forwards every remaining native <div> attribute. The decorative pattern and spotlight layers are aria-hidden. Set the --pattern-color CSS variable (via className or style) to recolor the texture - see Custom color.

Accessibility

The pattern and spotlight layers are aria-hidden and pointer-events-none, so they're skipped by assistive tech and never intercept clicks.
Content is wrapped, not replaced - your children stay in the normal flow and fully accessible.
The pattern is intentionally low-emphasis; ensure your foreground content keeps sufficient contrast against the background for it to stay readable.
The cursor spotlight honors prefers-reduced-motion - it's forced persistent (fade-free) when a user requests reduced motion.

Actions & Inputs

Data Display

Decoration & Effects

Layout

Menus

Navigation

Overlays

Status & Feedback