> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/paper-design/shaders/llms.txt
> Use this file to discover all available pages before exploring further.
# Quick Start
> Create your first Paper Shader in under 5 minutes
This guide will help you create your first animated shader. We'll build a beautiful mesh gradient background in both React and vanilla JavaScript.
## React Quick Start
If you haven't already, install the React package:
```bash theme={null}
npm install @paper-design/shaders-react
```
Import any shader component and add it to your React component:
```jsx App.jsx theme={null}
import { MeshGradient } from '@paper-design/shaders-react';
function App() {
return (
);
}
export default App;
```
Adjust the parameters to customize the appearance:
```jsx theme={null}
```
The shader automatically creates a `
## Vanilla JavaScript Quick Start
Install the vanilla JavaScript package:
```bash theme={null}
npm install @paper-design/shaders
```
Add a container element in your HTML:
```html index.html theme={null}
Paper Shaders Demo
```
Create a shader using the `ShaderMount` class:
```javascript main.js theme={null}
import {
ShaderMount,
meshGradientFragmentShader,
getShaderColorFromString,
ShaderFitOptions,
defaultObjectSizing
} from '@paper-design/shaders';
// Get the container element
const container = document.getElementById('shader-container');
// Define your shader uniforms
const uniforms = {
// Color configuration
u_colors: [
'#5100ff',
'#00ff80',
'#ffcc00',
'#ea00ff'
].map(getShaderColorFromString),
u_colorsCount: 4,
// Visual parameters
u_distortion: 1,
u_swirl: 0.8,
u_grainMixer: 0,
u_grainOverlay: 0,
// Sizing parameters
u_fit: ShaderFitOptions[defaultObjectSizing.fit],
u_rotation: 0,
u_scale: 1,
u_offsetX: 0,
u_offsetY: 0,
u_originX: 0.5,
u_originY: 0.5,
u_worldWidth: 1000,
u_worldHeight: 1000,
};
// Create the shader mount
const shader = new ShaderMount(
container,
meshGradientFragmentShader,
uniforms,
{}, // WebGL context attributes
0.2, // speed
0 // starting frame
);
// Clean up when done (e.g., on page navigation)
// shader.dispose();
```
You can dynamically update shader parameters:
```javascript theme={null}
// Update colors
shader.setUniforms({
u_colors: [
'#e0eaff',
'#241d9a',
'#f75092',
'#9f50d3'
].map(getShaderColorFromString),
u_distortion: 0.5,
});
// Change animation speed
shader.setSpeed(1);
// Pause animation
shader.setSpeed(0);
```
## Try Other Shaders
Paper Shaders includes many different effects. Here are some popular ones:
```jsx DotOrbit theme={null}
import { DotOrbit } from '@paper-design/shaders-react';
```
```jsx SmokeRing theme={null}
import { SmokeRing } from '@paper-design/shaders-react';
```
```jsx Metaballs theme={null}
import { Metaballs } from '@paper-design/shaders-react';
```
```jsx GodRays theme={null}
import { GodRays } from '@paper-design/shaders-react';
```
## Common Patterns
### Full-Page Background
```jsx theme={null}
import { MeshGradient } from '@paper-design/shaders-react';
function Layout({ children }) {
return (
{/* Background shader */}
{/* Content on top */}
{children}
);
}
```
### Static Shader (No Animation)
For better performance, set `speed={0}` to disable animation:
```jsx theme={null}
```
### Card Background
```jsx theme={null}
function Card({ children }) {
return (
{children}
);
}
```
### Masked with Text
```jsx theme={null}
function HeroText() {
return (
HELLO
);
}
```
## Performance Tips
Set `speed={0}` for static shaders to completely eliminate animation overhead and achieve zero ongoing performance cost.
The shader automatically limits resolution based on device capabilities. You can adjust `minPixelRatio` and `maxPixelCount` props for fine-tuning.
Shaders pause automatically when the browser tab is hidden to save resources.
## Next Steps
Learn about all React shader components and their props
Deep dive into the ShaderMount API for vanilla JavaScript
Explore all available shaders with live examples
Complete API documentation and type definitions
## Common Issues
Make sure the parent container has a defined width and height. The shader canvas matches its parent's dimensions.
```jsx theme={null}
{/* ❌ Parent has no height */}
{/* ✅ Parent has explicit height */}
```
Paper Shaders requires WebGL2 support. Ensure you're testing in a modern browser:
* Chrome 56+
* Firefox 51+
* Safari 15+
* Edge 79+
Try these optimizations:
1. Set `speed={0}` if animation isn't needed
2. Reduce the shader size using CSS
3. Lower the `minPixelRatio` prop (default is 2)
4. Set a lower `maxPixelCount` to cap resolution
```jsx theme={null}
```
Colors should be provided as CSS color strings. Valid formats:
* Hex: `'#ff0000'` or `'#f00'`
* RGB: `'rgb(255, 0, 0)'`
* RGBA: `'rgba(255, 0, 0, 0.5)'`
* Named: `'red'`
```jsx theme={null}
{/* ✅ Valid */}
{/* ❌ Invalid */}
```