gl-react

gl-react is designed for composing fragment shaders for 2D effects on images, videos, and other 2D assets.

Limitations:

• No 3D support: Vertex shaders and vertex data are currently out of scope. It is not intended for 3D use-cases.
• Workaround: If you need arbitrary WebGL calls or 3D capabilities, you should use the WebGL API (in web) or react-native-webgl (in React Native) and combine it with libraries like Three.js or PIXI.js.

The cookbook includes a WebGL Inspector designed for debugging shaders and uniforms. It provides:

• Real-time uniform values
• Shader source code display
• Performance metrics (FPS, draw calls, vertices)
• Toggle visibility for debugging

Use gl-react-image to render images within a gl-react surface. It provides various resizeMode options implemented in OpenGL. It is compatible with gl-react-dom, gl-react-expo, gl-react-native, and gl-react-headless surfaces.

Because GLImage renders a Node, it can be used as a texture input for other effects or as a source for effects.

import { Surface } from "gl-react-dom"; // or gl-react-expo / gl-react-native / gl-react-headless
import GLImage from "gl-react-image";

<Surface width={300} height={200}>
  <GLImage source="https://i.imgur.com/uTP9Xfr.jpg" resizeMode="cover" />
</Surface>;

To use gl-react-native in a React Native project, you must first ensure react-native-unimodules is installed and configured according to its official documentation.

Note: If you are using Expo, use gl-react-expo instead of gl-react-native.

You can run the GL React Cookbook development server either from the monorepo root or directly from the package directory. The cookbook will be available at http://localhost:3001.

# From the root of the monorepo:
pnpm install
pnpm cookbook

# Or directly from this package:
cd packages/cookbook
pnpm dev

To use the device camera as a texture in your shaders, you must install expo-camera and webgltexture-loader-expo-camera, then import the loader at your application's entry point.

yarn add expo-camera webgltexture-loader-expo-camera

// In your entry point file
import "webgltexture-loader-expo-camera";

Because gl-react uses typedarray-pool, which relies on Node.js's global object, you must define global as globalThis in your vite.config.js to avoid errors.

export default defineConfig({
  // ...
  define: {
    global: "globalThis",
  },
});

Choose the implementation package that matches your runtime environment:

• React DOM: Use gl-react-dom for web applications.
• React Native (Expo): Use gl-react-expo for iOS/Android via Expo GLView.
• React Native (Standard): Use gl-react-native for iOS/Android via unimodules.
• Node.js: Use gl-react-headless for server-side or headless environments (backed by headless-gl).