Ballmac UI home
Get Pro

WebGL CanvasPRO

New

Fills its parent with a fragment shader or a cloud of points. Theme colors, pointer and progress arrive as uniforms; it pauses off screen, lowers its resolution when slow, and holds still under reduced motion.

v1.0.0Updated Oct 26, 2026
What changed

Update without losing your edits

Drawn on the GPU

Move the pointer over it.

Installation

  1. Once per project: add the Pro registry and your licence key.

    components.json
    {
  "registries": {
    "@ballmac": "https://ui.ballmac.com/r/{name}.json",
    "@ballmac-pro": {
      "url": "https://ui.ballmac.com/r/pro/{name}.json",
      "headers": { "Authorization": "Bearer ${BALLMAC_LICENSE_KEY}" }
    }
  }
}
    .env.local
    BALLMAC_LICENSE_KEY=your-licence-key

  2. Add it.

    $ pnpm dlx shadcn@latest add @ballmac-pro/webgl-canvas

  3. Need a licence or help with setup?

    The source is part of Ballmac UI Pro.

    Log in with your licence key to read and copy it here, or install it through the shadcn CLI or the MCP server. You own the code once it is in your project.

    Get ProLog in

Usage

import { WebglCanvas } from "@/components/ballmac/webgl-canvas"

The full example is in the Code tab above.

API reference

PropTypeDefault
fragment*

GLSL ES 3.00 fragment shader body (no version line). It can read `uResolution`, `uTime`, `uPointer`, `uPointerDown`, `uProgress` and the uniforms below.

string—
vertex

Vertex shader body, for a cloud of `points` placed from `gl_VertexID`. Leave out for a full-screen shader.

string—
points

How many points to draw. Needs `vertex`.

number—
blend

How points blend: "add" glows on a dark ground, "alpha" is ordinary transparency.

"add" | "alpha"—
colors

Theme colors the shader reads, as `{ uniformName: "--css-variable" }`. Each becomes a `vec3` and follows light and dark.

Record<string, string>—
uniforms

Your own uniforms, applied once and whenever this prop changes.

Uniforms—
onFrame

Called every frame, before drawing, to return uniforms that change continuously (scroll position, momentum).

(frame: FrameInfo) => Uniforms | void—
progress

A value from 0 to 1 the shader reads as `uProgress`, for example scroll progress.

number0
maxDpr

Highest device pixel ratio to render at. Heavy shaders do well at 1.5.

number1.5
minScale

Lowest share of that resolution the adaptive quality may fall to when frames run slow.

number0.5
paused

Stops the scene, for example while a dialog is open.

booleanfalse
stillTime

The moment, in seconds, that is drawn once when the visitor prefers reduced motion.

number4
label

Describes the picture for assistive technology. Leave empty when the scene is only decoration.

string—
fallback

Shown instead of the scene when the browser or device cannot run WebGL.

React.ReactNode—

Also accepts the standard attributes of its root element.

Use with AI

Place <WebglCanvas fragment={glsl} colors={{ uAccent: '--primary' }} /> inside a relative container; write the picture as a GLSL ES 3.00 fragment shader reading uTime, uPointer, uProgress and your colors. With the shadcn MCP server set up (guide), ask your agent:

Add the Ballmac UI WebGL Canvas (@ballmac-pro/webgl-canvas) to this project with the shadcn MCP, then use it where it fits.

Use it for

  • A shader-drawn hero, background or product stage
  • Effects that must follow the theme tokens and stay still for people who ask for less motion

Not for

  • Soft CSS gradients and glows (aurora-background is lighter)
  • Many canvases on one page (each runs its own loop)

Registry JSON (needs your licence key): https://ui.ballmac.com/r/pro/webgl-canvas.json

Credits

Covered by the Ballmac UI Pro license.

npm
None
Registry
@ballmac/color@ballmac-pro/webglshadcn/utils

Pairs well with

Cover Art

Cover pictures drawn from a seed in your theme's chart colors: color fields, rings, bars, dots or waves. The same seed always draws the same picture, so an item without an image still looks finished.

Globe

An interactive WebGL dot globe (cobe) with markers, drag-to-spin momentum and arrow-key control. Colors come from theme tokens and repaint on theme change; starts lazily and pauses off-screen.

Grid Pattern

A crisp square-grid background in the border color with optional dashed lines, filled cells, softly lighting random cells and an edge fade, drawn as one SVG pattern.

Aurora Background

Soft, slowly drifting aurora light made of blurred token-colored glows with fine vertical curtains and an optional radial fade. Pure CSS layers, paused off-screen, still under reduced motion.