> ## 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.
# Sizing and Fit
> Guide to shader sizing, fit modes, and responsive behavior
## Overview
Paper Shaders provide powerful sizing controls to manage how shader graphics scale and fit within their containers. This guide covers the sizing system, fit modes, and responsive strategies.
## Container Sizing
Shaders automatically fill their container element:
```jsx theme={null}
// Use CSS to size the container
// Or use className
// With inline width/height props
```
```javascript theme={null}
// Size via CSS
const container = document.getElementById('shader-container');
container.style.width = '400px';
container.style.height = '400px';
const shaderMount = new ShaderMount(
container,
fragmentShader,
uniforms
);
```
Shader canvas automatically resizes when the container size changes using
ResizeObserver. No manual intervention needed.
## Fit Modes
The `fit` parameter controls how shader graphics scale within the container:
### None
No automatic fitting - renders at natural scale:
```jsx theme={null}
```
**Use cases:**
* Tiling patterns
* Precise pixel control
* Coordinated multi-shader layouts
### Contain
Fits entire graphic inside container while maintaining aspect ratio:
```jsx theme={null}
```
**Behavior:**
* Entire graphic visible
* May have empty space on sides
* Maintains aspect ratio
* Default for most object-based shaders
**Use cases:**
* Logos and graphics that must be fully visible
* Aspect-ratio-sensitive designs
* Card backgrounds
### Cover
Fills entire container while maintaining aspect ratio:
```jsx theme={null}
```
**Behavior:**
* Fills entire container
* May crop parts of graphic
* Maintains aspect ratio
* No empty space
**Use cases:**
* Hero backgrounds
* Full-bleed sections
* When cropping is acceptable
### Visual Comparison
```jsx None theme={null}
// Renders at natural scale, may overflow or have gaps
```
```jsx Contain theme={null}
// Fits entirely, may have letterboxing
```
```jsx Cover theme={null}
// Fills completely, may crop edges
```
## Sizing Parameters
Fine-tune shader positioning and scaling:
### Scale
Zoom the shader graphic:
```jsx theme={null}
// Scale range: 0.01 to 4
// Default: 1
```
`scale` applies after `fit` calculations, so `fit="contain"` + `scale={2}`
will contain the graphic then zoom it 2x (likely cropping).
### Rotation
Rotate the shader graphic:
```jsx theme={null}
// Range: 0 to 360 degrees
// Default: 0
```
### Origin
Set rotation and scaling pivot point:
```jsx theme={null}
// Default: originX={0.5}, originY={0.5} (center)
```
**Common origin points:**
* Top-left: `originX={0}`, `originY={0}`
* Top-center: `originX={0.5}`, `originY={0}`
* Center: `originX={0.5}`, `originY={0.5}` (default)
* Bottom-right: `originX={1}`, `originY={1}`
### Offset
Shift the graphic position:
```jsx theme={null}
// Range: -1 to 1 (relative to container)
// Default: offsetX={0}, offsetY={0}
```
### World Dimensions
Define virtual canvas size for precise control:
```jsx theme={null}
// Default: worldWidth={0}, worldHeight={0} (auto)
// When 0, uses container dimensions
```
**Use cases:**
* Matching shader scale across different containers
* Consistent sizing in responsive layouts
* Precise alignment with other elements
## Complete Sizing Example
Combine all sizing parameters:
```jsx theme={null}
```
## Sizing in Vanilla JS
Set sizing parameters as uniforms:
```javascript theme={null}
import { ShaderFitOptions } from '@paper-design/shaders';
const uniforms = {
// Shader-specific uniforms
u_colors: [/*...*/],
u_colorsCount: 3,
// Sizing uniforms
u_fit: ShaderFitOptions.cover, // 0=none, 1=contain, 2=cover
u_scale: 1.2,
u_rotation: 15,
u_originX: 0.3,
u_originY: 0.7,
u_offsetX: 0.1,
u_offsetY: -0.05,
u_worldWidth: 1200,
u_worldHeight: 800,
};
const shaderMount = new ShaderMount(
container,
fragmentShader,
uniforms
);
// Update sizing dynamically
shaderMount.setUniforms({
u_scale: 1.5,
u_rotation: 30,
});
```
## Responsive Strategies
### Fluid Container
Let shader scale naturally with container:
```jsx theme={null}
```
### Aspect Ratio Container
Maintain aspect ratio on resize:
```jsx theme={null}
```
### Breakpoint-Based Sizing
Adjust sizing parameters by screen size:
```jsx theme={null}
import { useState, useEffect } from 'react';
function ResponsiveSizing() {
const [scale, setScale] = useState(1);
useEffect(() => {
const updateScale = () => {
if (window.innerWidth < 768) setScale(0.8);
else if (window.innerWidth < 1024) setScale(1);
else setScale(1.2);
};
updateScale();
window.addEventListener('resize', updateScale);
return () => window.removeEventListener('resize', updateScale);
}, []);
return (
);
}
```
### Container Queries
Use container queries for component-level responsive sizing:
```css theme={null}
.shader-wrapper {
container-type: inline-size;
}
@container (min-width: 600px) {
.shader-container {
height: 400px;
}
}
@container (max-width: 599px) {
.shader-container {
height: 300px;
}
}
```
```jsx theme={null}
```
## Pattern vs Object Sizing
Different shader types have different default sizing:
### Pattern Shaders
Default: `fit="none"` for tiling:
```jsx theme={null}
import { defaultPatternSizing } from '@paper-design/shaders';
console.log(defaultPatternSizing);
// {
// fit: 'none',
// scale: 1,
// rotation: 0,
// offsetX: 0,
// offsetY: 0,
// originX: 0.5,
// originY: 0.5,
// worldWidth: 0,
// worldHeight: 0,
// }
// Examples: DotGrid, Waves, Voronoi
```
### Object Shaders
Default: `fit="contain"` for full visibility:
```jsx theme={null}
import { defaultObjectSizing } from '@paper-design/shaders';
console.log(defaultObjectSizing);
// {
// fit: 'contain',
// scale: 1,
// rotation: 0,
// offsetX: 0,
// offsetY: 0,
// originX: 0.5,
// originY: 0.5,
// worldWidth: 0,
// worldHeight: 0,
// }
// Examples: MeshGradient, Metaballs, SmokeRing
```
## Advanced: Coordinated Sizing
Sync sizing across multiple shaders:
```jsx theme={null}
function CoordinatedShaders() {
const [rotation, setRotation] = useState(0);
useEffect(() => {
const interval = setInterval(() => {
setRotation(r => (r + 1) % 360);
}, 50);
return () => clearInterval(interval);
}, []);
const sharedSizing = {
fit: 'cover',
scale: 1.5,
rotation,
worldWidth: 1000,
worldHeight: 1000,
};
return (
{/* Background layer */}
{/* Foreground layer */}
);
}
```
## Sizing Best Practices
* Use `cover` for backgrounds that should fill completely
* Use `contain` for graphics that must be fully visible
* Use `none` for tiling patterns and precise layouts
* Use percentage-based container widths
* Consider `aspect-ratio` CSS property
* Adjust `scale` parameter for mobile vs desktop
* Test on actual devices, not just browser resize
* Larger containers = more pixels = slower rendering
* Use `maxPixelCount` to limit rendering resolution
* Consider static shaders (`speed={0}`) for large areas
* See [Performance Guide](/guides/performance) for details
* Use matching `worldWidth` and `worldHeight`
* Share `rotation` and `scale` for synchronized effects
* Consider `offsetX`/`offsetY` for layered compositions
## Common Sizing Patterns
### Full-Screen Background
```jsx theme={null}
```
### Hero Section
```jsx theme={null}
```
### Card Background
```jsx theme={null}
```
### Tiling Pattern
```jsx theme={null}
```
## Troubleshooting
### Shader not visible
Ensure container has explicit width and height (CSS or inline)
Try `fit="cover"` to ensure shader fills container
Ensure `scale` isn't too large or `offset` isn't pushing content out
### Shader looks cropped
* Try `fit="contain"` instead of `cover`
* Reduce `scale` parameter
* Adjust `offset` to recenter
### Shader doesn't resize
* Verify container size actually changes (check DevTools)
* ResizeObserver works automatically - no manual action needed
* Check for fixed dimensions preventing resize
## Next Steps
Optimize shader resolution and rendering
Customize shader visual parameters
React-specific sizing patterns
Vanilla JS sizing control