Size Version Downloads Twitter Discord
# NPM npm install ogl react-ogl # Yarn yarn add ogl react-ogl # PNPM pnpm add ogl react-ogl
react-ogl itself is super minimal, but you can use the familiar @react-three/fiber API with some helpers targeted for different platforms:
This example uses create-react-app for the sake of simplicity, but you can use your own environment or create a codesandbox.
Show full example
# 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>, )
This example uses expo-cli but you can create a bare app with react-native CLI as well.
Show full example
# 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> )
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).
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>
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} /> }
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.
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} />
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>
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 attach={(parent, self) => (parent.setProperty(self), () => parent.removeProperty(self))} /> </parent>
Elements who extend OGL.Geometry or OGL.Program will automatically attach via attach="geometry" and attach="program", respectively.
<mesh> <box /> <normalProgram /> </mesh>
react-ogl tracks an internal catalog of constructable elements, defaulting to the OGL namespace. This catalog can be expanded via extend to declaratively use custom elements as native elements.
import { extend } from 'react-ogl' class CustomElement {} extend({ CustomElement }) <customElement />
TypeScript users will need to extend the OGLElements interface to describe custom elements and their properties.
import { OGLElement, extend } from 'react-ogl' class CustomElement {} declare module 'react-ogl' { interface OGLElements { customElement: OGLElement<typeof CustomElement> } } extend({ CustomElement })
Effectful elements that require a gl context can mark themselves as effectful and receive a OGLRenderingContext when constructed, making args mutable and enabling the use of props. This is done for OGL built-in elements like <mesh />, <geometry />, and <program />.
import { extend } from 'react-ogl' class CustomElement { constructor(gl) { this.gl = gl } } extend({ CustomElement }, true) <customElement />
Objects created outside of React (e.g. globally or from a loader) can be added to the scene-graph with the <primitive /> element via its object prop. Primitives can be interacted with like any other element, but will modify object and cannot make use of args.
import * as OGL from 'ogl' const object = new OGL.Transform() <primitive object={object} position={[1, 2, 3]} />
react-ogl ships with hooks that allow you to tie or request information to your components. These are called within the body of <Canvas /> and contain imperative and possibly stateful code.
Each <Canvas /> or Root encapsulates its own OGL state via React context and a Zustand store, as defined by RootState. This can be accessed and modified with the onCreated canvas prop, and with hooks like useOGL.
interface RootState { // Zustand setter and getter for live state manipulation. // See https://github.com/pmndrs/zustand get(): RootState set(fn: (previous: RootState) => (next: Partial<RootState>)): void // Canvas layout information size: { width: number; height: number } // OGL scene internals renderer: OGL.Renderer gl: OGL.OGLRenderingContext scene: OGL.Transform camera: OGL.Camera // OGL perspective and frameloop preferences orthographic: boolean frameloop: 'always' | 'never' // Internal XR manager to enable WebXR features xr: XRManager // Frameloop internals for custom render loops priority: number subscribed: React.RefObject<Subscription>[] subscribe: (refCallback: React.RefObject<Subscription>, renderPriority?: number) => void unsubscribe: (refCallback: React.RefObject<Subscription>, renderPriority?: number) => void // Optional canvas event manager and its state events?: EventManager mouse: OGL.Vec2 raycaster: OGL.Raycast hovered: Map<number, Instance<OGL.Mesh>['object']> }
Returns the current canvas' RootState, describing react-ogl state and OGL rendering internals (see root state).
const { renderer, gl, scene, camera, ... } = useOGL()
To subscribe to a specific key, useOGL accepts a Zustand selector:
const renderer = useOGL((state) => state.renderer)
Subscribes an element into a shared render loop outside of React. useFrame subscriptions are provided a live RootState, the current RaF time in seconds, and a XRFrame when in a WebXR session. Note: useFrame subscriptions should never update React state but prefer external mechanisms like refs.
const object = React.useRef<OGL.Transform>(null!) useFrame((state: RootState, time: number, frame?: XRFrame) => { object.current.rotation.x = time / 2000 object.current.rotation.y = time / 1000 }) return <transform ref={object} />
Synchronously loads and caches assets with a loader via suspense. Note: the caller component must be wrapped in React.Suspense.
const texture = useLoader(OGL.TextureLoader, '/path/to/image.jpg')
Multiple assets can be requested in parallel by passing an array:
const [texture1, texture2] = useLoader(OGL.TextureLoader, ['/path/to/image1.jpg', '/path/to/image2.jpg'])
Custom loaders can be implemented via the LoaderRepresentation signature:
class CustomLoader { async load(gl: OGLRenderingContext, url: string): Promise<void> {} } const result = useLoader(CustomLoader, '/path/to/resource')
Traverses an OGL.Transform for unique meshes and programs, returning an ObjectMap.
const { nodes, programs } = useGraph(object) <mesh geometry={nodes['Foo'].geometry} program={programs['Bar']} />
Returns the internal Zustand store. Useful for transient updates outside of React (e.g. multiplayer/networking).
const store = useStore() React.useLayoutEffect(() => store.subscribe(state => ...), [store])
Exposes an object's react-internal Instance state from a ref.
Note: this is an escape hatch to react-internal fields. Expect this to change significantly between versions.
const ref = React.useRef<OGL.Transform>() const instance = useInstanceHandle(ref) React.useLayoutEffect(() => { instance.parent.object.foo() }, []) <transform ref={ref} />
react-ogl implements mesh pointer-events with OGL.Raycast that can be tapped into via the following props:
<mesh // Fired when the mesh is clicked or tapped. onClick={(event: OGLEvent<MouseEvent>) => ...} // Fired when a pointer becomes inactive over the mesh. onPointerUp={(event: OGLEvent<PointerEvent>) => ...} // Fired when a pointer becomes active over the mesh. onPointerDown={(event: OGLEvent<PointerEvent>) => ...} // Fired when a pointer moves over the mesh. onPointerMove={(event: OGLEvent<PointerEvent>) => ...} // Fired when a pointer enters the mesh's bounds. onPointerOver={(event: OGLEvent<PointerEvent>) => ...} // Fired when a pointer leaves the mesh's bounds. onPointerOut={(event: OGLEvent<PointerEvent>) => ...} />
Events contain the original event as nativeEvent and properties from OGL.RaycastHit.
{ nativeEvent: PointerEvent | MouseEvent, localPoint: Vec3, distance: number, point: Vec3, faceNormal: Vec3, localFaceNormal: Vec3, uv: Vec2, localNormal: Vec3, normal: Vec3, }
Custom events can be implemented per the EventManager interface and passed via the events Canvas prop.
const events: EventManager = { connected: false, connect(canvas: HTMLCanvasElement, state: RootState) { // Bind handlers }, disconnect(canvas: HTMLCanvasElement, state: RootState) { // Cleanup }, } <Canvas events={events}> <mesh onPointerMove={(event: OGLEvent<PointerEvent>) => console.log(event)}> <box /> <normalProgram /> </mesh> </Canvas>
Full example
const events = { connected: false, connect(canvas: HTMLCanvasElement, state: RootState) { state.events.handlers = { pointermove(event: PointerEvent) { // Convert mouse coordinates state.mouse.x = (event.offsetX / state.size.width) * 2 - 1 state.mouse.y = -(event.offsetY / state.size.height) * 2 + 1 // Filter to interactive meshes const interactive: OGL.Mesh[] = [] state.scene.traverse((node: OGL.Transform) => { // Mesh has registered events and a defined volume if ( node instanceof OGL.Mesh && (node as Instance<OGL.Mesh>['object']).__handlers && node.geometry?.attributes?.position ) interactive.push(node) }) // Get elements that intersect with our pointer state.raycaster!.castMouse(state.camera, state.mouse) const intersects: OGL.Mesh[] = state.raycaster!.intersectMeshes(interactive) // Call mesh handlers for (const entry of intersects) { if ((entry as unknown as any).__handlers) { const object = entry as Instance<OGL.Mesh>['object'] const handlers = object.__handlers const handlers = object.__handlers handlers?.onPointerMove?.({ ...object.hit, nativeEvent: event }) } } }, } // Bind state.events.connected = true for (const [name, handler] of Object.entries(state.events.handlers)) { canvas.addEventListener(name, handler) } }, disconnect(canvas: HTMLCanvasElement, state: RootState) { // Unbind state.events.connected = false for (const [name, handler] of Object.entries(state.events.handlers)) { canvas.removeEventListener(name, handler) } }, } <Canvas events={events}> <mesh onPointerMove={(event: OGLEvent<PointerEvent>) => console.log(event)}> <box /> <normalProgram /> </mesh> </Canvas>
Portal children into a foreign OGL element via createPortal, which can modify children's RootState. This is particularly useful for postprocessing and complex render effects.
function Component { // scene & camera are inherited from portal parameters const { scene, camera, ... } = useOGL() } const scene = new OGL.Transform() const camera = new OGL.Camera() <transform> {createPortal(<Component />, scene, { camera }) </transform>
In addition to createRoot (see custom canvas), react-ogl exports an act method which can be used to safely flush async effects in tests. The following emulates a legacy root and asserts against RootState (see root state).
import * as React from 'react' import * as OGL from 'ogl' import { type Root, type RootStore, type RootState, createRoot } from 'react-ogl' it('tests against a react-ogl component or scene', async () => { const transform = React.createRef<OGL.Transform>() const root: Root = createRoot(document.createElement('canvas')) const store: RootStore = await React.act(async () => root.render(<transform ref={transform} />)) const state: RootState = store.getState() expect(transform.current).toBeInstanceOf(OGL.Transform) expect(state.scene.children).toStrictEqual([transform.current]) })