Dot grid background

A container that draws a dot or line grid behind its children, with a radial, top or no fade mask and an optional spotlight that brightens the grid around the pointer. The pattern is pure CSS from your foreground and chart tokens, the pointer is tracked through CSS variables so children never re-render, and it works for heroes, empty states and drop zones.

BackgroundsComponentTailwind v4

Source

"use client";

import { useRef, type CSSProperties, type HTMLAttributes, type PointerEvent } from "react";
import { cn } from "@/lib/utils";

export type DotGridBackgroundProps = HTMLAttributes<HTMLDivElement> & {
  /** Dots at each intersection, or a line grid. */
  variant?: "dots" | "lines";
  /** Cell size in pixels. */
  size?: number;
  /** Fade the pattern out: from the centre, from the top edge, or not at all. */
  mask?: "radial" | "top" | "none";
  /** Brighten the grid around the pointer. */
  spotlight?: boolean;
  /** Spotlight radius in pixels. */
  spotlightSize?: number;
  /** Where the spotlight rests when no pointer is over the area: hidden, or centred behind the content. */
  spotlightIdle?: "hide" | "center";
};

const MASKS = {
  radial: "radial-gradient(ellipse 72% 64% at 50% 45%, #000 35%, transparent 100%)",
  top: "linear-gradient(to bottom, #000 30%, transparent 95%)",
  none: "none",
};

function pattern(variant: "dots" | "lines", color: string) {
  return variant === "dots"
    ? `radial-gradient(circle at center, ${color} 1.1px, transparent 1.6px)`
    : `linear-gradient(to right, ${color} 1px, transparent 1px), linear-gradient(to bottom, ${color} 1px, transparent 1px)`;
}

export function DotGridBackground({
  variant = "dots",
  size = 24,
  mask = "radial",
  spotlight = false,
  spotlightSize = 260,
  spotlightIdle = "hide",
  className,
  children,
  style,
  onPointerMove,
  onPointerLeave,
  ...props
}: DotGridBackgroundProps) {
  const rootRef = useRef<HTMLDivElement>(null);
  const idle = spotlightIdle === "center";

  // Writes CSS variables directly so following the pointer never re-renders the children.
  const move = (event: PointerEvent<HTMLDivElement>) => {
    onPointerMove?.(event);
    const root = rootRef.current;
    if (!spotlight || !root) return;
    const box = root.getBoundingClientRect();
    root.style.setProperty("--chm-spot-x", `${event.clientX - box.left}px`);
    root.style.setProperty("--chm-spot-y", `${event.clientY - box.top}px`);
    root.dataset.spotlight = "on";
  };
  const leave = (event: PointerEvent<HTMLDivElement>) => {
    onPointerLeave?.(event);
    const root = rootRef.current;
    if (!root) return;
    root.style.setProperty("--chm-spot-x", "50%");
    root.style.setProperty("--chm-spot-y", "42%");
    root.dataset.spotlight = idle ? "idle" : "off";
  };

  const base = variant === "dots" ? "color-mix(in oklab, var(--foreground) 22%, transparent)" : "color-mix(in oklab, var(--foreground) 9%, transparent)";
  const lit = variant === "dots" ? "color-mix(in oklab, var(--foreground) 70%, transparent)" : "color-mix(in oklab, var(--foreground) 30%, transparent)";
  const tile = `${size}px ${size}px`;
  const offset = `${size / 2}px ${size / 2}px`;
  const spot = `radial-gradient(circle ${spotlightSize}px at var(--chm-spot-x) var(--chm-spot-y), #000 0%, transparent 100%)`;

  return (
    <div
      ref={rootRef}
      data-spotlight={spotlight ? (idle ? "idle" : "off") : undefined}
      onPointerMove={move}
      onPointerLeave={leave}
      style={{ "--chm-spot-x": "50%", "--chm-spot-y": "42%", ...style } as CSSProperties}
      className={cn("group/grid relative isolate overflow-hidden bg-background", className)}
      {...props}
    >
      <div aria-hidden="true" className="pointer-events-none absolute inset-0 -z-10" style={{ maskImage: MASKS[mask], WebkitMaskImage: MASKS[mask] }}>
        <div className="absolute inset-0" style={{ backgroundImage: pattern(variant, base), backgroundSize: tile, backgroundPosition: offset }} />
        {spotlight && (
          <>
            <div
              className={cn(
                "absolute inset-0 opacity-0 motion-safe:transition-opacity motion-safe:duration-300",
                "group-data-[spotlight=on]/grid:opacity-100 group-data-[spotlight=idle]/grid:opacity-100",
              )}
              style={{
                backgroundImage: `radial-gradient(circle ${spotlightSize}px at var(--chm-spot-x) var(--chm-spot-y), color-mix(in oklab, var(--chart-2) 16%, transparent), transparent 70%)`,
              }}
            />
            <div
              className={cn(
                "absolute inset-0 opacity-0 motion-safe:transition-opacity motion-safe:duration-300",
                "group-data-[spotlight=on]/grid:opacity-100",
              )}
              style={{ backgroundImage: pattern(variant, lit), backgroundSize: tile, backgroundPosition: offset, maskImage: spot, WebkitMaskImage: spot }}
            />
          </>
        )}
      </div>
      {children}
    </div>
  );
}