# ShaderGradient v2: a three.js gradient renderer with strict React and R3F pairings
> ruucm/shadergradient renders moving 3D gradients in React, Vue, Framer and Figma. v2 keeps only the renderer, so state, controls and peer dependencies are yours to manage.
**ruucm/shadergradient** — Create beautiful moving gradients on Framer, Figma and React
- Repository: https://github.com/ruucm/shadergradient
- Website: https://shadergradient.co
- Stars: 3,093 · Forks: 180
- Language: TypeScript
- License: not declared
- Published: 2026-10-08 · Updated: 2026-10-30 · Language: en
- Canonical page: https://hysenlabs.com/projects/ruucm-shadergradient
## ShaderGradient v2 ships a renderer and nothing else
Version 2 of ruucm/shadergradient cut the React package down to two exports: `ShaderGradient` and `ShaderGradientCanvas`. There is no built-in store and no control panel. If you want sliders for color or speed, you bring your own state or pair the renderer with `@shadergradient/ui`, which holds the stateless control components that were pulled out of the core package.
That split matters for anyone upgrading from the old build. `shadergradient-old` is the legacy v1 package that bundled the store and the UI together, and the repository tells you to keep using it only if you rely on that with-store build. Everything in v2 assumes you hold the gradient settings yourself, either as props or as a query string.
Customizable 3D, moving gradients are the whole product. The repository is TypeScript under the MIT license, credited to ruucm and stone-skipper, and its last push landed on 2026-09-23. GitHub lists no releases for it. Publishing goes through changesets, with `pnpm release` building the React and Vue packages before `changeset publish`.
## Four peer dependencies and a types package before anything renders
Installing `@shadergradient/react` alone is not enough. The instructions add `@react-three/fiber`, `three`, `three-stdlib` and `camera-controls` to the same command, plus `@types/three` as a dev dependency. Yarn, npm and pnpm each get their own pair of lines. The pnpm version reads:
```
# with pnpm
pnpm add @shadergradient/react @react-three/fiber three three-stdlib camera-controls
pnpm add -D @types/three
```
Your app owns the three.js version, then. The compatibility table asks for `three` at `>=0.158.0` in every environment it lists, so an older three.js in an existing project is the first thing to check before blaming the gradient component. The same install line also pulls react-three-fiber into projects that have never used it, which is a cost when the rest of the page is plain DOM. For the Vue package the same reasoning applies in the other direction: it renders through TresJS, so the dependency list there is different and lives in its own README.
## Next.js 15 App Router forces R3F v9 and React 19
`@shadergradient/react` itself works on React 18 or 19, but the right `@react-three/fiber` version depends on where it is mounted. For the Next.js 15 App Router, the compatibility matrix requires React `^19.0.0` and `@react-three/fiber` `^9.0.0`. R3F v8 is called structurally incompatible with the App Router's vendored React 19 canary, and the full trace lives in issue #138 on the repository.
Every other environment in the table (Next 14, Next 15 with the Pages router, Vite and similar) takes React `^18` or `^19` with a matching `8.x` or `9.x` release of `@react-three/fiber`. Stay on one of these combinations and no `next.config` aliases or `transpilePackages` entries are required.
A Next 15 project that still pins React 18 or R3F v8 therefore has to upgrade both packages before the gradient can render inside the App Router. The repository documents no workaround for staying on the old versions, so the upgrade is the price of entry on that stack. Next 14, Next 15 on the Pages router and Vite projects are not held to that pairing and can stay on React 18 with an 8.x release of `@react-three/fiber`, as long as the two versions match each other.
## Props or a query string: two ways to describe the same gradient
Basic usage places `ShaderGradient` inside `ShaderGradientCanvas`. Canvas-level props such as `pixelDensity` and `fov` sit on the wrapper, while `cDistance` and `cPolarAngle` sit on the child:
```tsx
import { ShaderGradientCanvas, ShaderGradient } from '@shadergradient/react'
function App() {
return (
)
}
```
The second route is a URL. Set `control='query'` and hand a string to `urlString`, for instance one copied from shadergradient.co/customize:
```tsx
```
The query string carries keys that mirror the props: `animate`, `cDistance`, `cPolarAngle`, `color1` through `color3`, `lightType`, `shader`, `type`, `uFrequency`, `uSpeed` and `uStrength`. The hosted customizer becomes the place where you design, and the package plays back what you copied out of it. The documented `type` values are `plane`, `sphere` and `waterPlane`.
## A mesh type with three colors, a motion range and a loop duration
The `MeshT` type in the README lists what a gradient can change. Motion comes from `animate` (`'on'` or `'off'`), `uTime`, `uSpeed`, `uStrength`, `uDensity`, `uFrequency` and `uAmplitude`. A `range` field accepts `'enabled'` or `'disabled'` and pairs with `rangeStart` and `rangeEnd`. `loop` and `loopDuration` control repetition. Placement uses `positionX`, `positionY`, `positionZ` and the matching `rotationX`, `rotationY`, `rotationZ`.
Color comes from `color1`, `color2` and `color3`. There is no fourth color field in the listed type, so a gradient here has three. `reflection` takes a number, `wireframe` a boolean, and `shader` a string. The listing breaks off at `rotSpringOption`, so what that option accepts is not documented in the README.
`ShaderGradientCanvas` adds its own settings: `envBasePath`, the GL overrides `preserveDrawingBuffer` and `powerPreference`, and lazy loading through `lazyLoad`, `threshold` and `rootMargin`. The README gives no values or defaults for the lazy-load trio, so you read the source to learn what `threshold` expects.
## The UI package is an ESM bundle, and Vue lives in a second README
`@shadergradient/ui` is the odd one in the lineup. It is not published to npm and is consumed as an ESM bundle built from `packages/ui`. The Framer and Figma integrations still use it internally, so a React developer who wants prebuilt controls cannot run an install command for it.
Framer and Figma are the no-code entry points. Figma gets a community plugin. Framer gets a component: copy the URL https://framer.com/m/ShaderGradient-oWuS.js and paste it on the Framer canvas. Neither route needs an npm install. The Framer remix project is marked login required.
Vue 3 and Nuxt have their own package, `@shadergradient/vue`, which renders through TresJS and ships an SSR-safe canvas for Nuxt. Install commands, component examples, SSR fallbacks and supported dependency versions live in `packages/shadergradient-vue/README.md`, so the Vue path needs a second document. Starters exist for CRA, Next.js (Pages and App Router), Vite with React 19, Vue with Vite, and Nuxt.
## Shader code is still not a standalone package, and Webflow and Wix are unchecked
The roadmap in the README separates what shipped from what did not. Checked: detaching the framer-motion peer dependency by splitting UI and store, Figma GIF support, the three.js upgrade, separate Framer component bundles and the Framer plugin. Unchecked: more shaders such as metallic and glass, Webflow support and Wix support.
One unchecked item has practical weight: separating the shader code into its own package so JavaScript, Vue and others can reuse it. Until that box is ticked, the repository documents no entry point for the shaders outside the React and Vue renderers. Anyone on Webflow or Wix has no supported route yet, because both platforms sit on the unchecked part of the list and the repository points to no plugin or component for either.
Contributors run `pnpm install` and `pnpm dev` from the root, where `dev` calls `turbo run dev --parallel`. Browser tests run with `pnpm test:e2e` through Playwright. Releasing uses `pnpm changeset`, `pnpm version-packages` and then `pnpm release`. The root `package.json` declares `node >=14.0.0` and `pnpm >=10.2.1`, while `packageManager` pins `pnpm@10.12.4`.
## Conclusion
Adopt it if you want an animated three.js background in React, Vue, Framer or Figma and are happy to manage gradient state yourself, ideally through a URL copied from shadergradient.co/customize. Skip it for Next 15 App Router projects that cannot move to React 19 and R3F v9, and for pages where adding three.js is too heavy. Check your three.js version against the >=0.158.0 floor before anything else.
## FAQ
### How to use shader gradient in Figma?
Install the Figma plugin linked in the repository from the Figma community page. Figma GIF support is ticked as done on the project roadmap.
### How to use shader gradient in Framer?
Copy the component URL https://framer.com/m/ShaderGradient-oWuS.js and paste it on the Framer canvas. A Framer remix project is also linked, and it requires a login.
### How to use shader gradient in React?
Install @shadergradient/react with its peer dependencies, then place ShaderGradient inside ShaderGradientCanvas and set props such as cDistance and cPolarAngle. Settings can also come from a URL with control='query'.
## Sources
- [Issues](https://github.com/ruucm/shadergradient/issues)
- [Project website](https://shadergradient.co)
- [README](https://github.com/ruucm/shadergradient/blob/main/README.md)
- [ruucm/shadergradient on GitHub](https://github.com/ruucm/shadergradient)
---
Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ruucm-shadergradient