glsl-react

A React library for rendering WebGL shaders with a simple, declarative API. Write GLSL fragment shaders and render them as React components with minimal setup. It has no dependencies.

Features

• 🎨 Simple declarative API - Render shaders as React components
• 🔧 Built-in uniforms - Automatic time, resolution, and mouse position tracking
• 🖼️ Texture support - Load images, videos, and canvas elements as textures
• 📊 Performance monitoring - Built-in FPS and frame time telemetry
• 🎯 TypeScript first - Full type safety and IntelliSense support
• ⚡ Optimized rendering - Efficient uniform updates and texture management
• 🪝 Composable hooks - Build custom shader components with low-level hooks
• 📦 Zero dependencies - Lightweight and no external runtime dependencies

Installation

npm install glsl-react

yarn add glsl-react

pnpm add glsl-react

Quick Start

import { ShaderCanvas } from 'glsl-react';

const fragmentShader = `
  precision mediump float;
  uniform vec2 u_resolution;
  uniform float u_time;

  void main() {
    vec2 uv = gl_FragCoord.xy / u_resolution;
    vec3 color = 0.5 + 0.5 * cos(u_time + uv.xyx + vec3(0, 2, 4));
    gl_FragColor = vec4(color, 1.0);
  }
`;

function App() {
  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <ShaderCanvas fragmentShader={fragmentShader} />
    </div>
  );
}

Core Concepts

Built-in Uniforms

The library automatically provides three essential uniforms:

• u_resolution (vec2) - Canvas dimensions in pixels
• u_time (float) - Time in seconds since shader started
• u_mouse (vec2) - Normalized mouse position [0, 1]

Custom Uniforms

Pass custom uniforms to your shader. Important: Always memoize the uniforms object to prevent unnecessary re-renders and performance issues:

import { useMemo } from 'react';

function MyShader() {
  const [scale, setScale] = useState(2.0);
  const [color, setColor] = useState([1.0, 0.5, 0.2]);

  const uniforms = useMemo<Uniforms>(() => ({
    u_color: { type: 'vec3', value: color },
    u_scale: { type: 'float', value: scale },
    u_matrix: { type: 'mat4', value: new Float32Array(16) }
  }), [color, scale]);

  return <ShaderCanvas fragmentShader={shader} uniforms={uniforms} />;
}

Texture Uniforms

Load images, videos, or canvas elements as textures:

import { useMemo, useState, useEffect } from 'react';

function TextureShader() {
  const [image, setImage] = useState<HTMLImageElement | null>(null);

  useEffect(() => {
    const img = new Image();
    img.src = '/path/to/texture.jpg';
    img.onload = () => setImage(img);
  }, []);

  const uniforms = useMemo<Uniforms>(() => {
    if (!image) return {};
    
    return {
      u_texture: {
        type: 'texture',
        value: image,
        options: {
          wrapS: TextureWrap.REPEAT,
          wrapT: TextureWrap.REPEAT,
          minFilter: TextureFilter.LINEAR,
          magFilter: TextureFilter.LINEAR,
          flipY: true
        }
      }
    };
  }, [image]);

  if (!image) return <div>Loading...</div>;

  return <ShaderCanvas fragmentShader={shader} uniforms={uniforms} />;
}

Performance Monitoring

Track shader performance with the built-in telemetry hook:

import { ShaderCanvas, useShaderTelemetry } from 'glsl-react';

function App() {
  const { onFrameRender, Telemetry } = useShaderTelemetry({
    position: 'top-right'
  });

  return (
    <>
      <ShaderCanvas
        fragmentShader={shader}
        onFrameRender={onFrameRender}
      />
      <Telemetry />
    </>
  );
}

API Reference

ShaderCanvas

Main component for rendering WebGL shaders.

Props:

| Prop | Type | Required | Description | |------|------|----------|-------------| | fragmentShader | string | Yes | GLSL fragment shader source code | | vertexShader | string | No | Custom vertex shader (defaults to fullscreen quad) | | uniforms | Uniforms | No | Custom uniform values | | pixelRatio | number | No | Pixel ratio for high-DPI displays (default: window.devicePixelRatio) | | style | CSSProperties | No | CSS styles for canvas element | | className | string | No | CSS class name | | options | ShaderCanvasOptions | No | Additional configuration options | | onFrameRender | (frameTime: number) => void | No | Callback fired after each frame |

Uniform Types

Supported uniform types:

• Scalars: float, int
• Vectors: vec2, vec3, vec4, ivec2, ivec3, ivec4
• Matrices: mat3, mat4
• Textures: texture

Texture Configuration

TextureWrap enum:

• REPEAT - Repeat texture
• CLAMP_TO_EDGE - Clamp to edge
• MIRRORED_REPEAT - Mirror and repeat

TextureFilter enum:

• NEAREST - Nearest neighbor filtering
• LINEAR - Linear filtering
• NEAREST_MIPMAP_NEAREST - Nearest mipmap, nearest filtering
• LINEAR_MIPMAP_NEAREST - Linear mipmap, nearest filtering
• NEAREST_MIPMAP_LINEAR - Nearest mipmap, linear filtering
• LINEAR_MIPMAP_LINEAR - Linear mipmap, linear filtering

Hooks

useShaderTelemetry(props?)

Creates performance monitoring for shader rendering.

const { onFrameRender, Telemetry } = useShaderTelemetry({
  position: 'top-right',
  updateInterval: 100,
  graphSamples: 60
});

useWebGL(canvasRef, uniformsRef, vertexShader, fragmentShader)

Low-level hook for WebGL context and shader program management.

useTextures(gl, uniforms)

Manages WebGL textures from uniform definitions.

useMousePosition(elementRef)

Tracks normalized mouse position [0, 1] within an element.

useResizeObserver(elementRef, callback)

Observes element resize with efficient ResizeObserver API.

Advanced Usage

Custom Vertex Shader

const vertexShader = `
  attribute vec2 a_position;
  varying vec2 v_uv;
  
  void main() {
    v_uv = a_position * 0.5 + 0.5;
    gl_Position = vec4(a_position, 0.0, 1.0);
  }
`;

<ShaderCanvas
  vertexShader={vertexShader}
  fragmentShader={fragmentShader}
/>

Custom Built-in Uniform Names

<ShaderCanvas
  fragmentShader={shader}
  options={{
    builtInUniforms: {
      u_time: 'time',
      u_resolution: 'resolution',
      u_mouse: 'mouse'
    }
  }}
/>

Video Textures

import { useMemo, useState } from 'react';

function VideoShader() {
  const [video] = useState(() => {
    const vid = document.createElement('video');
    vid.src = '/path/to/video.mp4';
    vid.loop = true;
    vid.play();
    return vid;
  });

  const uniforms = useMemo<Uniforms>(() => ({
    u_video: {
      type: 'texture',
      value: video
    }
  }), [video]);

  return <ShaderCanvas fragmentShader={shader} uniforms={uniforms} />;
}

Forwarding Canvas Ref

const canvasRef = useRef<HTMLCanvasElement>(null);

<ShaderCanvas
  ref={canvasRef}
  fragmentShader={shader}
/>

Examples

Animated Gradient

const shader = `
  precision mediump float;
  uniform vec2 u_resolution;
  uniform float u_time;

  void main() {
    vec2 uv = gl_FragCoord.xy / u_resolution;
    vec3 color = 0.5 + 0.5 * cos(u_time + uv.xyx + vec3(0, 2, 4));
    gl_FragColor = vec4(color, 1.0);
  }
`;

Mouse-Interactive Shader

const shader = `
  precision mediump float;
  uniform vec2 u_resolution;
  uniform vec2 u_mouse;

  void main() {
    vec2 uv = gl_FragCoord.xy / u_resolution;
    float dist = distance(uv, u_mouse);
    vec3 color = vec3(1.0 - smoothstep(0.0, 0.3, dist));
    gl_FragColor = vec4(color, 1.0);
  }
`;

Texture Mapping

import { useMemo, useState, useEffect } from 'react';

function TextureMappingExample() {
  const [image, setImage] = useState<HTMLImageElement | null>(null);

  useEffect(() => {
    const img = new Image();
    img.src = '/texture.jpg';
    img.onload = () => setImage(img);
  }, []);

  const shader = `
    precision mediump float;
    uniform vec2 u_resolution;
    uniform sampler2D u_texture;

    void main() {
      vec2 uv = gl_FragCoord.xy / u_resolution;
      vec4 texColor = texture2D(u_texture, uv);
      gl_FragColor = texColor;
    }
  `;

  const uniforms = useMemo<Uniforms>(() => {
    if (!image) return {};
    return {
      u_texture: { type: 'texture', value: image }
    };
  }, [image]);

  if (!image) return <div>Loading...</div>;

  return <ShaderCanvas fragmentShader={shader} uniforms={uniforms} />;
}

Browser Support

This library requires WebGL support. It works in all modern browsers:

• Chrome/Edge 9+
• Firefox 4+
• Safari 5.1+
• Opera 12+
• iOS Safari 8+
• Android Browser 4.4+

Performance Tips

1. Memoize uniforms object - Always wrap uniforms in useMemo() to prevent unnecessary updates
2. Minimize uniform updates - Only include changing values in dependency array
3. Use appropriate texture sizes - Large textures impact performance
4. Optimize shader complexity - Complex calculations affect frame rate
5. Monitor performance - Use useShaderTelemetry to track metrics
6. Consider pixel ratio - Lower pixel ratio improves performance on high-DPI displays

License

MIT

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Support

• 🐛 Report bugs
• 💡 Request features
• 📖 Documentation (WIP)