# 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 free components with the shadcn CLI as below, and Pro components with the gradients.sh CLI (`npx gradients.sh add `, https://www.npmjs.com/package/gradients.sh). It logs the computer in to the user's Pro account with a one-click approval the first time, then runs shadcn with the token. Scripts can also use the HTTP API (https://gradients.sh/openapi.json). ## 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 Pro: install those with `npx gradients.sh add `, which handles the login and the token (see Pro setup). Before a shadcn install, check the project has a `components.json`; if not, run `npx shadcn@latest init` (`npx gradients.sh add` does this itself). 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 gradients.sh add border-beam` - [Contour](https://gradients.sh/docs/pro/contour.md): Hairline contour lines flowing over a slowly breathing terrain. Install: `npx gradients.sh add 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 gradients.sh add 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 gradients.sh add 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 gradients.sh add dither-chart` - [Dither Gradient](https://gradients.sh/docs/pro/dither-gradient.md): A dusk sky dithered in your exact palette. Install: `npx gradients.sh add 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 gradients.sh add 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 gradients.sh add 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 gradients.sh add 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 gradients.sh add 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 gradients.sh add 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 gradients.sh add 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 gradients.sh add 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 gradients.sh add light-trails` - [Liquid Blob](https://gradients.sh/docs/pro/liquid-blob.md): A drop of liquid chrome slowly reshaping in a studio. Install: `npx gradients.sh add liquid-blob` - [Oscilloscope](https://gradients.sh/docs/pro/oscilloscope.md): A Lissajous figure turning on an analogue oscilloscope. Install: `npx gradients.sh add oscilloscope` - [Prism](https://gradients.sh/docs/pro/prism.md): Prism light falling across a wall, splitting into its spectrum. Install: `npx gradients.sh add prism` - [Reeded Glass](https://gradients.sh/docs/pro/reeded-glass.md): Soft light refracted through a pane of fluted glass. Install: `npx gradients.sh add reeded-glass` - [Risograph](https://gradients.sh/docs/pro/risograph.md): A two-ink risograph print with halftone screens and misregistration. Install: `npx gradients.sh add 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 gradients.sh add 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 gradients.sh add spotlight-grid` ## Pro setup Pro items install only for a gradients.sh account with Pro. The gradients.sh CLI does the login, the registries and the install in one command. Run it from the project folder: ```bash npx gradients.sh add ``` `` is a component (`god-rays`), a namespaced name (`@gradients-pro/god-rays`, `@gradients-config/`, `@gradients-saved/`) or a gradients.sh link. The command finds the project's `components.json` (running `shadcn init` if there is none), adds the gradients.sh registries to it, and runs `shadcn add` with the token. Flags such as `--overwrite` go through to shadcn. If shadcn stops to ask about overwriting a file that already exists, rerun with `--overwrite` only if the user agrees. The first time on a computer, the user approves a login: 1. The command prints a link and a code, then exits with code 2. Nothing in the project has changed yet. 2. Show the user the link and the code. 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. 3. When they say they approved, run the same command again. It picks up the approval and installs. If they haven't approved yet, it waits up to 30 seconds and prints the link again. The login is saved for the whole computer in the user's config folder (`~/.config/gradients.sh/`), not in the project, so there is nothing to commit or gitignore and later installs in any project skip the approval. `npx gradients.sh whoami` shows the account, `npx gradients.sh logout` revokes it, and `npx gradients.sh token` prints the token for scripts. A `GRADIENTS_TOKEN` set in the environment (CI) takes precedence over the login. If the command says the account has no Pro plan, tell the user: plans are at https://gradients.sh/pricing. ### Without the CLI For tools that can't run Node, or to wire the token in by hand: 1. Start a device login: ```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 approve as above. 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. (`npx gradients.sh login --project` does this step too.) 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 with `npx shadcn@latest add @gradients-pro/` (or `@gradients-config/`, `@gradients-saved/`). The shadcn 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, log in 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 page, in plain HTML, React, Vue or Svelte, with nothing to install. - [Technical 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 one command: npx gradients.sh add. - [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. ## Blog - [Red gradients in CSS: palettes, hex codes and blends that stay red](https://gradients.sh/blog/red-gradient-css): Red gradient palettes with hex codes, why red turns pink as it fades and maroon as it darkens, and how to blend red in CSS. - [Gradient backgrounds for websites: full-page CSS that stays readable and fast](https://gradients.sh/blog/gradient-background-website): How to add a gradient background to a website: full-page CSS without stripes, text that passes contrast, hero heights on phones, and smooth scrolling. - [Green gradients in CSS: palettes, hex codes and blends that stay green](https://gradients.sh/blog/green-gradient-css): Green gradient palettes with hex codes, why bright greens rarely carry white text, and how to blend green in CSS. - [Purple gradients in CSS: palettes, hex codes and blends that stay violet](https://gradients.sh/blog/purple-gradient-css): Purple gradient palettes with hex codes, why violet turns pink or blue as it fades, and how to blend it in CSS. - [Blue gradients in CSS: palettes, hex codes and blends that stay blue](https://gradients.sh/blog/blue-gradient-css): Blue gradient palettes with hex codes, why blue drifts purple or cyan as it fades, and the CSS fix. - [Pastel gradients in CSS: palettes, hex codes and soft blends](https://gradients.sh/blog/pastel-gradient-css): Pastel gradient palettes with hex codes, the OKLCH numbers behind pastel, and blends that stay soft. - [Sunset gradients in CSS: palettes, hex codes and a setting sun](https://gradients.sh/blog/sunset-gradient-css): Sunset gradient palettes with hex codes, CSS that keeps the middle from going muddy, and an animated sun. - [Metallic gradients in CSS: chrome, gold, copper and rose gold](https://gradients.sh/blog/metallic-gradient-css): CSS recipes with hex codes for chrome, gold, copper and rose gold, plus brushed metal and a sheen. - [Ordered dithering in a shader: Bayer matrices for gradients](https://gradients.sh/blog/ordered-dithering-shader): How Bayer dithering works, a tested GLSL shader to paste, and when noise beats it for gradient banding. - [uiGradients alternatives for CSS and animated gradients](https://gradients.sh/blog/uigradients-alternatives): Gradient collections, CSS generators and live components to use instead of uiGradients, and when to keep it. - [WebGPU vs WebGL2 for UI backgrounds](https://gradients.sh/blog/webgpu-vs-webgl-ui-backgrounds): Whether WebGPU makes an animated gradient faster than WebGL2, with frame times from one engine running both, browser support and a fallback plan. - [CSS gradient vs WebGL gradient: which one for an animated background](https://gradients.sh/blog/css-gradient-vs-webgl-gradient): When a CSS gradient is enough, when WebGL is worth it, and what each costs, with a Chrome paint trace. - [ShaderGradient alternatives for animated gradients](https://gradients.sh/blog/shadergradient-alternatives): Lighter React libraries, no-code editors and video exporters to use instead of ShaderGradient, and when to keep it. - [Grainient alternatives for gradient backgrounds](https://gradients.sh/blog/grainient-alternatives): Free and paid alternatives to Grainient, from grainy mesh generators to live gradients you install in code. - [How to make a mesh gradient in CSS and React](https://gradients.sh/blog/mesh-gradient-css-react): Three ways to build a mesh gradient: stacked radial gradients in CSS, a static image, or a live WebGL component. - [How to add film grain to a gradient on a website](https://gradients.sh/blog/film-grain-gradient-css): Grainy gradients with an SVG noise tile in CSS or per-pixel grain in a shader, and what each costs. - [How to make a gradient follow light and dark mode](https://gradients.sh/blog/gradient-light-dark-mode): Theme-aware gradients with CSS variables and light-dark(), and the catch for canvas and WebGL. - [React libraries for animated gradient backgrounds, compared](https://gradients.sh/blog/react-animated-gradient-libraries): Paper Shaders, Hazeglow, ShaderGradient, NEAT and more, with measured bundle sizes and trade-offs. - [Animated gradient backgrounds in Tailwind CSS](https://gradients.sh/blog/tailwind-animated-gradient): Animate a gradient background in Tailwind v4 with one keyframe, blurred blobs, or a live shader. - [Background video vs animated gradient: what a hero costs](https://gradients.sh/blog/background-video-vs-animated-gradient): Measured file sizes for hero background videos, why grain makes them huge, and when a live gradient wins. - [How to make a seamless looping gradient animation](https://gradients.sh/blog/seamless-looping-gradient-animation): Why gradient loops jump, and how to build one that doesn't in CSS or in a shader. - [Gradient text in Tailwind CSS, static and animated](https://gradients.sh/blog/gradient-text-tailwind): Make gradient text with Tailwind's bg-clip-text, animate it with one keyframe, or fill it with a live shader. - [Stripe gradient animation in React: how it works and how to build it](https://gradients.sh/blog/stripe-gradient-animation-react): How the copied Stripe Gradient.js really draws its gradient, what it leaves out, and a maintained React version with a slanted edge. - [Animated gradient border in CSS, Tailwind and React](https://gradients.sh/blog/animated-gradient-border-react): A pure CSS conic border, or a live GPU border with a transparent inside, for cards and buttons. - [Aurora background effect in React](https://gradients.sh/blog/aurora-background-react): Add a moving northern-lights background to a React or Next.js section in your own colours. - [Export an animated gradient as a seamless MP4 loop](https://gradients.sh/blog/export-animated-gradient-mp4-loop): Turn a moving gradient into an MP4 that loops with no seam, then use it on the web, in slides or in a video edit. - [Animated gradient background for shadcn/ui](https://gradients.sh/blog/animated-gradient-background-shadcn): Add a moving gradient background to a shadcn/ui or React app with one CLI command, in your theme colours. ## 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 add ` installs any component, logging the computer in to Pro on first use. Also `login`, `whoami`, `logout` and `token`. - [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.