react-ogl

<p align="left"> <a id="cover" href="#cover"> <picture> <source media="(prefers-color-scheme: dark)" srcset=".github/dark.svg"> <img style="white-space:pre-wrap" alt="Build OGL scenes declaratively with re-usable, self-contained components that react to state, are readily interactive and can participate in React's ecosystem.&#10&#10react-ogl is a barebones react renderer for OGL with an emphasis on minimalism and modularity. Its reconciler simply expresses JSX as OGL elements — <mesh /> becomes new OGL.Mesh(). This happens dynamically; there's no wrapper involved."> </picture> </a> </p>

Installation
Getting Started
- react-dom
- react-native
Canvas
- Canvas Props
- Custom Canvas
Creating Elements
Hooks
Events
- Custom Events
Portals
Testing

Installation

# NPM
npm install ogl react-ogl

# Yarn
yarn add ogl react-ogl

# PNPM
pnpm add ogl react-ogl

Getting Started

react-ogl itself is super minimal, but you can use the familiar @react-three/fiber API with some helpers targeted for different platforms:

react-dom

This example uses create-react-app for the sake of simplicity, but you can use your own environment or create a codesandbox.

<details> <summary>Show full example</summary> <br />

# Create app
npx create-react-app my-app
cd my-app

# Install dependencies
npm install ogl react-ogl

# Start
npm run start

The following creates a re-usable component that has its own state, reacts to events and participates a shared render-loop.

import * as React from 'react'
import { useFrame, Canvas } from 'react-ogl'
import { createRoot } from 'react-dom/client'

function Box(props) {
  // This reference will give us direct access to the mesh
  const mesh = React.useRef()
  // Set up state for the hovered and active state
  const [hovered, setHover] = React.useState(false)
  const [active, setActive] = React.useState(false)
  // Subscribe this component to the render-loop, rotate the mesh every frame
  useFrame(() => (mesh.current.rotation.x += 0.01))
  // Return view, these are regular OGL elements expressed in JSX
  return (
    <mesh
      {...props}
      ref={mesh}
      scale={active ? 1.5 : 1}
      onClick={() => setActive((value) => !value)}
      onPointerOver={() => setHover(true)}
      onPointerOut={() => setHover(false)}
    >
      <box />
      <program
        vertex={`
          attribute vec3 position;
          attribute vec3 normal;

          uniform mat4 modelViewMatrix;
          uniform mat4 projectionMatrix;
          uniform mat3 normalMatrix;

          varying vec3 vNormal;

          void main() {
            vNormal = normalize(normalMatrix * normal);
            gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
          }
        `}
        fragment={`
          precision highp float;

          uniform vec3 uColor;
          varying vec3 vNormal;

          void main() {
            vec3 normal = normalize(vNormal);
            float lighting = dot(normal, normalize(vec3(10)));

            gl_FragColor.rgb = uColor + lighting * 0.1;
            gl_FragColor.a = 1.0;
          }
        `}
        uniforms={{ uColor: hovered ? 'hotpink' : 'orange' }}
      />
    </mesh>
  )
}

createRoot(document.getElementById('root')).render(
  <Canvas camera={{ position: [0, 0, 8] }}>
    <Box position={[-1.2, 0, 0]} />
    <Box position={[1.2, 0, 0]} />
  </Canvas>,
)

</details>

react-native

This example uses expo-cli but you can create a bare app with react-native CLI as well.

<details> <summary>Show full example</summary> <br />

# Create app and cd into it
npx expo init my-app # or npx react-native init my-app
cd my-app

# Automatically install & link expo modules
npx install-expo-modules@latest
expo install expo-gl

# Install NPM dependencies
npm install ogl react-ogl

# Start
npm run start

We'll also need to configure metro.config.js to look for the mjs file extension that OGL uses.

module.exports = {
  resolver: {
    resolverMainFields: ['browser', 'exports', 'main'], // https://github.com/facebook/metro/issues/670
    sourceExts: ['json', 'js', 'jsx', 'ts', 'tsx', 'cjs', 'mjs'],
    assetExts: ['glb', 'gltf', 'png', 'jpg'],
  },
}

Inside of our app, you can use the same API as web while running on native OpenGL ES — no webview needed.

import * as React from 'react'
import { useFrame, Canvas } from 'react-ogl'

function Box(props) {
  // This reference will give us direct access to the mesh
  const mesh = React.useRef()
  // Set up state for the hovered and active state
  const [hovered, setHover] = React.useState(false)
  const [active, setActive] = React.useState(false)
  // Subscribe this component to the render-loop, rotate the mesh every frame
  useFrame(() => (mesh.current.rotation.x += 0.01))
  // Return view, these are regular OGL elements expressed in JSX
  return (
    <mesh
      {...props}
      ref={mesh}
      scale={active ? 1.5 : 1}
      onClick={() => setActive((value) => !value)}
      onPointerOver={() => setHover(true)}
      onPointerOut={() => setHover(false)}
    >
      <box />
      <program
        vertex={`
          attribute vec3 position;
          attribute vec3 normal;

          uniform mat4 modelViewMatrix;
          uniform mat4 projectionMatrix;
          uniform mat3 normalMatrix;

          varying vec3 vNormal;

          void main() {
            vNormal = normalize(normalMatrix * normal);
            gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
          }
        `}
        fragment={`
          precision highp float;

          uniform vec3 uColor;
          varying vec3 vNormal;

          void main() {
            vec3 normal = normalize(vNormal);
            float lighting = dot(normal, normalize(vec3(10)));

            gl_FragColor.rgb = uColor + lighting * 0.1;
            gl_FragColor.a = 1.0;
          }
        `}
        uniforms={{ uColor: hovered ? 'hotpink' : 'orange' }}
      />
    </mesh>
  )
}

export default () => (
  <Canvas camera={{ position: [0, 0, 8] }}>
    <Box position={[-1.2, 0, 0]} />
    <Box position={[1.2, 0, 0]} />
  </Canvas>
)

</details>

Canvas

react-ogl provides an x-platform <Canvas /> component for web and native that serves as the entrypoint for your OGL scenes. It is a real DOM canvas or native view that accepts OGL elements as children (see creating elements).

Canvas Props

In addition to its platform props, <Canvas /> accepts a set of RenderProps to configure react-ogl and its rendering behavior.

<Canvas
  // Configures the react rendering mode. Defaults to `blocking`
  mode={"legacy" | "blocking" | "concurrent"}
  // Creates, sets, or configures the default renderer.
  // Accepts a callback, an external renderer, or renderer constructor params/properties.
  // Defaults to `new OGL.Renderer({ alpha: true, antialias: true, powerPreference: 'high-performance' })
  renderer={(canvas: HTMLCanvasElement) => new Renderer(canvas) | renderer | { ...params, ...props }}
  // Sets the renderer pixel ratio from a clamped range or value. Default is `[1, 2]`
  dpr={[min, max] | value}
  // Sets or configures the default camera.
  // Accepts an external camera, or camera constructor params/properties.
  // Defaults to `new OGL.Camera(gl, { fov: 75, near: 1, far: 1000 })` with position-z `5`
  camera={camera | { ...params, ...props }}
  // Enables orthographic projection when using OGL's built-in camera. Default is `false`
  orthographic={true | false}
  // Defaults to `always`
  frameloop={'always' | 'never'}
  // An optional callback invoked after canvas creation and before commit.
  onCreated={(state: RootState) => void}
  // Optionally configures custom events. Defaults to built-in events exported as `events`
  events={EventManager | undefined}
>
  {/* Accepts OGL elements as children */}
  <transform />
</Canvas>

// e.g.

<Canvas
  renderer={{ alpha: true }}
  camera={{ fov: 45, position: [0, 1.3, 3] }}
  onCreated={(state) => void state.gl.clearColor(1, 1, 1, 0)}
>
  <transform />
</Canvas>

Custom Canvas

A react 18 style createRoot API creates an imperative Root with the same options as <Canvas />, but you're responsible for updating it and configuring things like events (see events). This root attaches to an HTMLCanvasElement and renders OGL elements into a scene. Useful for creating an entrypoint with react-ogl and for headless contexts like a server or testing (see testing).

import { createRoot, events } from 'react-ogl'

const canvas = document.querySelector('canvas')
const root = createRoot(canvas, { events })
root.render(
  <mesh>
    <box />
    <normalProgram />
  </mesh>,
)
root.unmount()

createRoot can also be used to create a custom <Canvas />. The following constructs a custom canvas that renders its children into react-ogl.

import * as React from 'react'
import { createRoot, events } from 'react-ogl'

function CustomCanvas({ children }) {
  // Init root from canvas
  const [canvas, setCanvas] = React.useState()
  const root = React.useMemo(() => canvas && createRoot(canvas, { events }), [canvas])
  // Render children as a render-effect
  root?.render(children)
  // Cleanup on unmount
  React.useEffect(() => () => root?.unmount(), [root])
  // Use callback-style ref to access canvas in render
  return <canvas ref={setCanvas} />
}

Creating elements

react-ogl renders React components into an OGL scene-graph, and can be used on top of other renderers like react-dom and react-native that render for web and native, respectively. react-ogl components are defined by primitives or lower-case elements native to the OGL namespace (for custom elements, see extend).

function Component(props) {
  return (
    <mesh {...props}>
      <box />
      <normalProgram />
    </mesh>
  )
}

;<transform>
  <Component position={[1, 2, 3]} />
</transform>

These elements are not exported or implemented internally, but merely expressed as JSX — <mesh /> becomes new OGL.Mesh(). This happens dynamically; there's no wrapper involved.

JSX, properties, and shortcuts

react-ogl elements can be modified with JSX attributes or props. These are native to their underlying OGL objects.

<transform
  // Set non-atomic properties with literals
  // transform.visible = false
  visible={false}
  // Copy atomic properties with a stable reference (e.g. useMemo)
  // transform.rotation.copy(rotation)
  rotation={rotation}
  // Set atomic properties with declarative array syntax
  // transform.position.set(1, 2, 3)
  position={[1, 2, 3]}
  // Set scalars with shorthand for vector properties
  // transform.scale.set(1, 1, 1)
  scale={1}
  // Set CSS names or hex values as shorthand for color properties
  // transform.color.set('red')
  color="red"
  // Set sub properties with prop piercing or dash-case
  // transform.rotation.x = Math.PI / 2
  rotation-x={Math.PI / 2}
/>

Setting constructor arguments via `args`

An array of constructor arguments (args) can be passed to instantiate elements' underlying OGL objects. Changing args will reconstruct the object and update any associated refs.

// new OGL.Text({ font, text: 'Text' })
<text args={[{ font, text: 'Text' }]} />

Built-in elements that require a gl context such as <mesh />, <geometry />, or <program /> are marked as effectful (see extend) and do not require an OGLRenderingContext to be passed via args. They can be constructed mutably and manipulated via props:

<mesh>
  <box />
  <normalProgram />
</mesh>

<geometry /> and <program /> also accept attributes and shader sources as props, which are passed to their respective constructors. This does not affect other properties like drawRange or uniforms.

<mesh>
  <geometry
    position={{ size: 3, data: new Float32Array([-0.5, 0.5, 0, -0.5, -0.5, 0, 0.5, 0.5, 0, 0.5, -0.5, 0]) }}
    uv={{ size: 2, data: new Float32Array([0, 1, 1, 1, 0, 0, 1, 0]) }}
    index={{ data: new Uint16Array([0, 1, 2, 1, 3, 2]) }}
  />
  {/* prettier-ignore */}
  <program
    vertex={/* glsl */ `...`}
    fragment={/* glsl */ `...`}
    uniforms={{ uniform: value }}
  />
</mesh>

Attaching into element properties via `attach`

Some elements do not follow the traditional scene-graph and need to be added by other means. For this, the attach prop can describe where an element is added via a property or a callback to add & remove the element.

// Attaches into parent.property, parent.sub.property, and parent.array[0]
<parent>
  <element attach="property" />
  <element attach="sub-property" />
  <element attach="array-0" />
</parent>

// Attaches via parent#setProperty and parent#removeProperty
<parent>
  <element
    attach={(parent, self) => {
      parent.setProperty(self)
      return () => parent.removeProperty(self)
    }}
    // lambda version