ruucm / shadergradient

# Shader Gradient v2
Customizable 3D, moving gradient for React. The v2 package is lean: it only ships the `ShaderGradient` renderer (and its canvas helper), while the stateless UI pieces now live in the separate `@shadergradient/ui` package.
# Table of contents
- 📦 Installation
- 📦 Packages
- 💻 Usage
- 📚 Examples
- 🎤 Conference Talks
- 📝 Contributing
- 🚀 Future Plan
- ⚖️ License
# Installation
## Figma
Figma Plugin
## Framer
Framer Component (Copy this URL and paste it on Framer Canvas)
## React
Install the core renderer and its peer deps.
 [code] 
Need the stateless control surfaces? Pull them from the `@shadergradient/ui` package (ESM build used by Framer/Figma), not from `@shadergradient/react`.
### Compatibility matrix
`@shadergradient/react` itself works on React 18 or 19, but the right `@react-three/fiber` version depends on your environment. **For Next.js 15 App Router specifically**, you must use R3F v9 + React 19 — R3F v8 is structurally incompatible with the App Router's vendored React 19 canary (see #138 for the full trace).
| Environment | React | @react-three/fiber | three |
| ------------------------------------- | -------------- | -------------------- | ----------- |
| **Next 15 — App Router** | `^19.0.0` | `^9.0.0` | `>=0.158.0` |
| Next 14 / Next 15 Pages / Vite / etc. | `^18` or `^19` | matching `8.x`/`9.x` | `>=0.158.0` |
No `next.config` aliases or `transpilePackages` entries are required when you stay on these combinations.
## Vue 3 and Nuxt
Use `ShaderGradient` inside `ShaderGradientCanvas` from `@shadergradient/vue`.
See installation and Vue/Nuxt usage
for installation commands, component examples, SSR fallbacks, and supported
dependency versions.
# Packages
- `@shadergradient/react`
 - Ships only the renderer: `ShaderGradient` and `ShaderGradientCanvas`.
 - No built-in store or controls. Use your own state or pair with `@shadergradient/ui`.
- `@shadergradient/ui`
 - Stateless UI/control components extracted from the core package for Framer/Figma usage.
 - Not published to npm; consumed as an ESM bundle (see `packages/ui`).
- `@shadergradient/vue`
 - Vue 3 renderer using TresJS, with an SSR-safe canvas for Nuxt usage.
 - See Vue setup and Nuxt usage.
- `shadergradient-old`
 - Legacy v1 package that bundled store + UI. Keep using this only if you rely on the old with-store build.
# Usage
Drop `ShaderGradient` inside `ShaderGradientCanvas` and drive it with props or a query string.
 [code] 
Load settings from a URL (for example, one copied from shadergradient.co/customize):
 [code] 
### Available Gradient Properties (Types)
 [code] 
`ShaderGradientCanvas` also accepts `pixelDensity`, `fov`, `envBasePath`, GL overrides (`preserveDrawingBuffer`, `powerPreference`), and lazy-load controls (`lazyLoad`, `threshold`, `rootMargin`).
# Examples
- Development apps versus standalone starters
- CRA Starter: CodeSandbox
- Next.js Starter (App Router): CodeSandbox
- Next.js Starter: CodeSandbox
- Vite + React 19 Starter: CodeSandbox
- Vu