# gradients.sh > Live, animated gradient backgrounds for React. Components render with WebGPU or WebGL2, loop seamlessly, follow CSS variables, and install into a project as source code with the shadcn CLI. Free components are MIT licensed; Pro components and presets need a paid account. ## When to use gradients.sh Reach for gradients.sh when a user wants a moving, living background or surface in a React app, for example: - A hero section, landing page or app background with a slow animated gradient (mesh, aurora, waves, grain, radial glow, linear flow). - Gradient text, an animated gradient border, a gradient button or a gradient card. - Pro effects: cursor glows, glass panels, god rays, light trails, dither and contour shaders, border beams, and dithered avatars, charts and progress bars. - Matching a look from a gradients.sh link the user pasted, or from one of the 207 named presets. Don't use it for a static CSS `linear-gradient` (write the CSS) or for colour palettes. Outside React, plain HTML pages can use the embed script: https://gradients.sh/docs/guides/embed.md. The components draw with WebGPU or WebGL2; a browser with neither keeps a CSS gradient behind the canvas. How to call it: install components with the shadcn CLI as below. Scripts and agents can also use the HTTP API (https://gradients.sh/openapi.json) and the CLI on npm (`npx gradients.sh login`, https://www.npmjs.com/package/gradients.sh), which connects a Pro account with a device login. ## Install from a gradients.sh link Users often paste a gradients.sh link and ask you to add that gradient to their project. Every page has a Markdown version with the exact install command for the settings in the link. Get it by sending `Accept: text/markdown`, or by adding `.md` to the path and keeping the query string exactly as it is (the query holds the user's settings): - https://gradients.sh/studio/blue-hour?c= → https://gradients.sh/studio/blue-hour.md?c= - https://gradients.sh/studio?c= → https://gradients.sh/studio.md?c= - https://gradients.sh/create?g= → https://gradients.sh/create.md?g= - https://gradients.sh/docs/components/aurora → https://gradients.sh/docs/components/aurora.md - https://gradients.sh/presets → https://gradients.sh/presets.md A link ending in `.json` under https://gradients.sh/r/ is already a shadcn registry item: install it with `npx shadcn@latest add `. Items under `/r/pro/`, and configs or saves built on a Pro component, need the Pro setup and an install by name instead. Before installing, check the project has a `components.json`; if not, run `npx shadcn@latest init`. After installing, place the component where the user asked, give it a size (it fills its box), and run the project's build or dev server to check it. ## Free components - [Mesh Gradient](https://gradients.sh/docs/components/mesh-gradient.md): Soft colour blobs drifting into each other. Install: `npx shadcn@latest add https://gradients.sh/r/mesh-gradient.json` - [Grain Gradient](https://gradients.sh/docs/components/grain-gradient.md): A grainy, out-of-focus blend of saturated colour. Install: `npx shadcn@latest add https://gradients.sh/r/grain-gradient.json` - [Aurora](https://gradients.sh/docs/components/aurora.md): Vertical light curtains folding over a night sky. Install: `npx shadcn@latest add https://gradients.sh/r/aurora.json` - [Waves](https://gradients.sh/docs/components/waves.md): Layered bands of colour rolling past each other. Install: `npx shadcn@latest add https://gradients.sh/r/waves.json` - [Radial Glow](https://gradients.sh/docs/components/radial-glow.md): A warm glow rising from the bottom edge. Install: `npx shadcn@latest add https://gradients.sh/r/radial-glow.json` - [Linear Flow](https://gradients.sh/docs/components/linear-flow.md): A linear blend whose angle and colour stops drift slowly. Install: `npx shadcn@latest add https://gradients.sh/r/linear-flow.json` - [Gradient Text](https://gradients.sh/docs/components/gradient-text.md): Real, selectable text filled with a live gradient. Install: `npx shadcn@latest add https://gradients.sh/r/gradient-text.json` - [Gradient Border](https://gradients.sh/docs/components/gradient-border.md): An animated gradient border around any content. The inside stays transparent. Install: `npx shadcn@latest add https://gradients.sh/r/gradient-border.json` - [Gradient Button](https://gradients.sh/docs/components/gradient-button.md): A button with a live gradient fill and hover, press, focus and disabled states. Install: `npx shadcn@latest add https://gradients.sh/r/gradient-button.json` - [Hero Background](https://gradients.sh/docs/components/hero-background.md): A full-bleed hero section on a live gradient that fades into the page. Install: `npx shadcn@latest add https://gradients.sh/r/hero-background.json` - [Section Fade](https://gradients.sh/docs/components/section-fade.md): A section whose live gradient fades out at its edges. Install: `npx shadcn@latest add https://gradients.sh/r/section-fade.json` - [Gradient Card](https://gradients.sh/docs/components/gradient-card.md): A card on a live gradient, with a scrim that keeps white text legible. Install: `npx shadcn@latest add https://gradients.sh/r/gradient-card.json` To install by name (`@gradients/`), add `"@gradients": "https://gradients.sh/r/{name}.json"` under `registries` in `components.json`. ## Pro components - [Border Beam](https://gradients.sh/docs/pro/border-beam.md): A short beam of dithered light that travels around a card's border, spilling a little light inward. Install: `npx shadcn@latest add @gradients-pro/border-beam` - [Contour](https://gradients.sh/docs/pro/contour.md): Hairline contour lines flowing over a slowly breathing terrain. Install: `npx shadcn@latest add @gradients-pro/contour` - [Cursor Glow](https://gradients.sh/docs/pro/cursor-glow.md): A dithered spotlight that follows the pointer across a field of unlit dots. Install: `npx shadcn@latest add @gradients-pro/cursor-glow` - [Dither Avatars](https://gradients.sh/docs/pro/dither-avatars.md): Overlapping avatars in halftone dither. Hovering or focusing one resolves it into the photo and names it. Install: `npx shadcn@latest add @gradients-pro/dither-avatars` - [Dither Chart](https://gradients.sh/docs/pro/dither-chart.md): An area chart filled with ordered dither, hot along the line and sparse at the baseline, with a lit column under the active point. Install: `npx shadcn@latest add @gradients-pro/dither-chart` - [Dither Gradient](https://gradients.sh/docs/pro/dither-gradient.md): A dusk sky dithered in your exact palette. Install: `npx shadcn@latest add @gradients-pro/dither-gradient` - [Dither Progress](https://gradients.sh/docs/pro/dither-progress.md): A progress bar whose fill climbs the palette toward a hot leading edge that breaks into pixels. Indeterminate mode sweeps a dithered comet. Install: `npx shadcn@latest add @gradients-pro/dither-progress` - [Dither Reveal](https://gradients.sh/docs/pro/dither-reveal.md): An image held in a few dithered palette tones that dissolves, cell by cell, into the real photo on hover, focus or scroll. Install: `npx shadcn@latest add @gradients-pro/dither-reveal` - [Eclipse](https://gradients.sh/docs/pro/eclipse.md): A total eclipse with a diamond-ring bead and a slowly turning corona. Install: `npx shadcn@latest add @gradients-pro/eclipse` - [Glass Panel](https://gradients.sh/docs/pro/glass-panel.md): Frosted glass over a live dither field: crisp pixels around the panel, melted colour through it, and a sheen that follows the pointer. Install: `npx shadcn@latest add @gradients-pro/glass-panel` - [Glow Command](https://gradients.sh/docs/pro/glow-command.md): A command menu whose active row is lit from its left edge by dithered light. Install: `npx shadcn@latest add @gradients-pro/glow-command` - [Glow Tabs](https://gradients.sh/docs/pro/glow-tabs.md): Underline tabs where dithered light rises from the active line. Full keyboard support. Install: `npx shadcn@latest add @gradients-pro/glow-tabs` - [God Rays](https://gradients.sh/docs/pro/god-rays.md): Soft shafts of light falling through haze from a high window. Install: `npx shadcn@latest add @gradients-pro/god-rays` - [Light Trails](https://gradients.sh/docs/pro/light-trails.md): A long-exposure bundle of light trails sweeping across the frame. Install: `npx shadcn@latest add @gradients-pro/light-trails` - [Liquid Blob](https://gradients.sh/docs/pro/liquid-blob.md): A drop of liquid chrome slowly reshaping in a studio. Install: `npx shadcn@latest add @gradients-pro/liquid-blob` - [Oscilloscope](https://gradients.sh/docs/pro/oscilloscope.md): A Lissajous figure turning on an analogue oscilloscope. Install: `npx shadcn@latest add @gradients-pro/oscilloscope` - [Prism](https://gradients.sh/docs/pro/prism.md): Prism light falling across a wall, splitting into its spectrum. Install: `npx shadcn@latest add @gradients-pro/prism` - [Reeded Glass](https://gradients.sh/docs/pro/reeded-glass.md): Soft light refracted through a pane of fluted glass. Install: `npx shadcn@latest add @gradients-pro/reeded-glass` - [Risograph](https://gradients.sh/docs/pro/risograph.md): A two-ink risograph print with halftone screens and misregistration. Install: `npx shadcn@latest add @gradients-pro/risograph` - [Scroll Stir](https://gradients.sh/docs/pro/scroll-stir.md): A topographic map in hairline contours and dithered elevation. A fast scroll twists the terrain, then it settles. Install: `npx shadcn@latest add @gradients-pro/scroll-stir` - [Spotlight Grid](https://gradients.sh/docs/pro/spotlight-grid.md): One dithered light under a grid of cards. It follows the pointer across the gaps and catches each card's hairline border. Install: `npx shadcn@latest add @gradients-pro/spotlight-grid` ## Pro setup Pro items install only for a gradients.sh account with Pro, through a personal token. Skip step 1 if `GRADIENTS_TOKEN` is already set in `.env.local` or `.env`. 1. Connect this project to the user's account with a device login. Start it: ```bash curl -s -X POST https://gradients.sh/api/agent/login -H 'content-type: application/json' -d '{"client":""}' ``` The response has `verificationUrl`, `userCode`, `deviceCode`, `interval` and `expiresIn`. Show the user the link and the code, and ask them to open the link, check the code matches, and approve. They sign in there if needed. Never open or approve the link yourself. Then poll every `interval` seconds until it answers 200 (it expires after `expiresIn` seconds): ```bash curl -s -X POST https://gradients.sh/api/agent/login/token -H 'content-type: application/json' -d '{"deviceCode":""}' ``` - 202 `{"status":"pending"}`: not approved yet, keep polling. - 200 `{"status":"approved","token":"gcn_pat_..."}`: done. - 403 `denied`, 410 `expired`: stop and tell the user. Write the token to `.env.local` as `GRADIENTS_TOKEN=gcn_pat_...` and make sure `.env.local` is in `.gitignore`. Don't print the token in your reply or commit it. The shadcn CLI reads `.env.local` itself. The user can revoke it on https://gradients.sh/account. 2. Add the gradients.sh registries to `components.json` (merge with any `registries` already there): ```json { "registries": { "@gradients": "https://gradients.sh/r/{name}.json", "@gradients-pro": { "url": "https://gradients.sh/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${GRADIENTS_TOKEN}" } }, "@gradients-config": { "url": "https://gradients.sh/r/c/{name}.json", "headers": { "Authorization": "Bearer ${GRADIENTS_TOKEN}" } }, "@gradients-saved": { "url": "https://gradients.sh/r/s/{name}.json", "headers": { "Authorization": "Bearer ${GRADIENTS_TOKEN}" } } } } ``` 3. Install Pro items by name (`@gradients-pro/`, `@gradients-config/`, `@gradients-saved/`). The CLI sends the token only for namespaced names, never for a bare URL. A 401 means no token was sent; a 403 means the token is wrong, revoked, unused for 90 days, or the account has no Pro (https://gradients.sh/pricing). For a 403 with Pro, run step 1 again for a new token. Tools that speak the OAuth 2.0 device grant (RFC 8628) can use it instead of step 1: the server metadata is at https://gradients.sh/.well-known/oauth-authorization-server. ## Presets 207 tuned presets (39 free). Each has a studio page, https://gradients.sh/studio/, whose Markdown version has its install command. The full list: https://gradients.sh/presets.md ## Docs - [Aurora](https://gradients.sh/docs/components/aurora.md): Vertical light curtains folding over a night sky. Works well behind dark sections and pricing tables. - [Gradient Border](https://gradients.sh/docs/components/gradient-border.md): An animated gradient border around any content. The inside stays transparent. - [Gradient Button](https://gradients.sh/docs/components/gradient-button.md): A button with a live gradient fill and hover, press, focus and disabled states. - [Gradient Card](https://gradients.sh/docs/components/gradient-card.md): A card on a live gradient, with a scrim that keeps white text legible. - [Gradient Text](https://gradients.sh/docs/components/gradient-text.md): Real, selectable text filled with a live gradient. - [Grain Gradient](https://gradients.sh/docs/components/grain-gradient.md): A grainy, out-of-focus blend of saturated colour, like a long-exposure photo. The grain is rendered per pixel, so it stays sharp at any size. - [Hero Background](https://gradients.sh/docs/components/hero-background.md): A full-bleed hero section on a live gradient that fades into the page. - [Components](https://gradients.sh/docs/components.md): Twelve free, MIT-licensed components. Every one runs live below. - [Linear Flow](https://gradients.sh/docs/components/linear-flow.md): A linear blend whose angle and colour stops drift slowly. The quietest kind: good behind dense content. - [Mesh Gradient](https://gradients.sh/docs/components/mesh-gradient.md): Soft colour blobs drifting into each other. A good default for hero sections and large panels. - [Radial Glow](https://gradients.sh/docs/components/radial-glow.md): A warm glow rising from the bottom edge. Use it under a headline or at the foot of a page. - [Section Fade](https://gradients.sh/docs/components/section-fade.md): A section whose live gradient fades out at its edges. - [Waves](https://gradients.sh/docs/components/waves.md): Layered bands of colour rolling past each other. The defaults are light, for light sections; pass a dark palette for dark ones. - [Introduction](https://gradients.sh/docs/getting-started.md): Animated GPU gradients for React. Install them with the shadcn CLI and own the code. - [Installation](https://gradients.sh/docs/getting-started/install.md): Add a moving gradient to a React app in three steps. - [Theming](https://gradients.sh/docs/getting-started/theming.md): Use your CSS variables so gradients follow your theme and dark mode. - [AI agents](https://gradients.sh/docs/guides/agents.md): Paste a gradients.sh link into Claude Code, Codex or Cursor and let it install the gradient. - [Embed](https://gradients.sh/docs/guides/embed.md): Put a live gradient on any HTML page, without React or a build step. - [FAQ](https://gradients.sh/docs/guides/faq.md): Browser support, performance, licensing and other common questions. - [Presets and exports](https://gradients.sh/docs/guides/presets.md): Start from a preset, tune it, then install it as a component or export it as a PNG or MP4. - [Border Beam](https://gradients.sh/docs/pro/border-beam.md): A beam of dithered light that travels around a card's border. - [Contour](https://gradients.sh/docs/pro/contour.md): Hairline contour lines flowing over a slowly breathing terrain. - [Cursor Glow](https://gradients.sh/docs/pro/cursor-glow.md): A dithered spotlight that follows the pointer. - [Dither Avatars](https://gradients.sh/docs/pro/dither-avatars.md): Avatars in halftone dither that resolve into photos on hover. - [Dither Chart](https://gradients.sh/docs/pro/dither-chart.md): An area chart filled with ordered dither. - [Dither Gradient](https://gradients.sh/docs/pro/dither-gradient.md): A dusk sky dithered in your exact palette. - [Dither Progress](https://gradients.sh/docs/pro/dither-progress.md): A progress bar whose leading edge breaks into pixels. - [Dither Reveal](https://gradients.sh/docs/pro/dither-reveal.md): An image that resolves from dithered palette tones into the photo. - [Eclipse](https://gradients.sh/docs/pro/eclipse.md): A total eclipse with a diamond-ring bead and a slowly turning corona. - [Glass Panel](https://gradients.sh/docs/pro/glass-panel.md): Frosted glass over a live dither field. - [Glow Command](https://gradients.sh/docs/pro/glow-command.md): A command menu with a dithered light on the active row. - [Glow Tabs](https://gradients.sh/docs/pro/glow-tabs.md): Underline tabs with dithered light rising from the active line. - [God Rays](https://gradients.sh/docs/pro/god-rays.md): Soft shafts of light falling through haze from a high window. - [Pro components](https://gradients.sh/docs/pro.md): Interactive and textured components, installed with the shadcn CLI after a one-command setup. - [Light Trails](https://gradients.sh/docs/pro/light-trails.md): A long-exposure bundle of light trails sweeping across the frame. - [Liquid Blob](https://gradients.sh/docs/pro/liquid-blob.md): A drop of liquid chrome slowly reshaping in a studio. - [Oscilloscope](https://gradients.sh/docs/pro/oscilloscope.md): A Lissajous figure turning on an analogue oscilloscope. - [Prism](https://gradients.sh/docs/pro/prism.md): Prism light falling across a wall, splitting into its spectrum. - [Reeded Glass](https://gradients.sh/docs/pro/reeded-glass.md): Soft light refracted through a pane of fluted glass. - [Risograph](https://gradients.sh/docs/pro/risograph.md): A two-ink risograph print with halftone screens and misregistration. - [Scroll Stir](https://gradients.sh/docs/pro/scroll-stir.md): A topographic map that swirls when the page scrolls fast. - [Spotlight Grid](https://gradients.sh/docs/pro/spotlight-grid.md): One dithered light under a grid of cards. ## Optional - [OpenAPI spec](https://gradients.sh/openapi.json): the registry, device login and OAuth endpoints. Tokens carry one scope, `registry:read` (https://gradients.sh/.well-known/oauth-protected-resource). - [CLI](https://www.npmjs.com/package/gradients.sh): `npx gradients.sh login` connects a project to a Pro account. - [About](https://gradients.sh/about) and [Contact](https://gradients.sh/contact). - [Agent skill](https://gradients.sh/skill.md): these instructions as a skill file for Claude Code, Codex and other agents. - [Free registry index](https://gradients.sh/r/registry.json) and [Pro registry index](https://gradients.sh/r/pro/registry.json), for `npx shadcn@latest search` and shadcn's MCP server.