react-zdog

library1.2.2jsnpmunverified

React-Zdog is a declarative React Fiber renderer for Zdog, a 'cute pseudo 3D engine'. It enables developers to integrate Zdog scenes directly into their React applications, leveraging React's component model for building reusable 3D elements with reactive state semantics. The library abstracts Zdog's imperative API into a set of declarative React components like `Illustration` and `Shape`, and provides hooks such as `useRender`, `useZdog`, and `useInvalidate` for finer-grained control over the Zdog instance and its rendering lifecycle. The current stable version is 1.2.2. While there isn't an explicit release cadence, it tends to update in response to changes in React or Zdog. Its key differentiator is simplifying Zdog development for React users, offering a more intuitive and component-based approach compared to direct Zdog API manipulation.

ai-ml llm-agents

npm install react-zdog

github ↗package ↗

INSTALL

IMPORT

SIG · REACT-ZDOG

react-zdog

ai-mljavascriptv1.2.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Illustration

✓ import { Illustration } from 'react-zdog'

✗ const Illustration = require('react-zdog').Illustration

Primary container for Zdog scenes, forwards props to Zdog.Illustration instance. Prefer named ESM imports in modern React.

Shape

✓ import { Shape } from 'react-zdog'

✗ import Shape from 'react-zdog/Shape'

Represents a basic Zdog shape. All Zdog components are named exports.

useRender

✓ import { useRender } from 'react-zdog'

✗ const useRender = require('react-zdog').useRender

A React hook giving access to the render loop. Must be called inside an <Illustration> component.

useInvalidate

✓ import { useInvalidate } from 'react-zdog'

A React hook providing a function to force a single scene frame update. Only useful when Illustration's `frameloop` prop is set to 'demand'.

Demonstrates rendering a basic blue Zdog shape within a full-viewport React application using the Illustration component.

import ReactDOM from "react-dom"; import React from "react"; import { Illustration, Shape } from "react-zdog"; function App() { return ( <div style={{ width: '100vw', height: '100vh', background: '#f0f0f0' }}> <Illustration zoom={8} style={{ display: 'block' }}> <Shape stroke={20} color="lightblue" rotate={{ x: Math.PI }} /> </Illustration> </div> ); } ReactDOM.render( <App />, document.getElementById("root") );

Debug

Known issues

gotchaAll React-Zdog hooks (e.g., `useRender`, `useZdog`, `useInvalidate`) must be used exclusively within the scope of an `<Illustration>` component, as they rely on its context for updates and state. Using them outside will result in runtime errors.

fix

Ensure all `react-zdog` hooks are direct or indirect children of an `<Illustration>` component.

affects: >=1.0.0

gotchaThe `useInvalidate()` hook is only effective when the `<Illustration>` component's `frameloop` prop is explicitly set to `'demand'`. If `frameloop` is `'always'` (the default), changes will re-render automatically, and `useInvalidate()` calls will have no observable effect.

fix

Set `<Illustration frameloop='demand' />` when using `useInvalidate()` for explicit render control. Otherwise, allow `frameloop='always'` for continuous rendering.

affects: >=1.0.0

gotchaTo enable pointer events (like `onClick`, `onPointerMove`) on Zdog elements, you must explicitly set the `pointerEvents` prop to `true` on the `<Illustration>` component. By default, pointer events are disabled.

fix

Add `pointerEvents={true}` to your `<Illustration>` component to enable event listeners on child Zdog elements.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'rotate')

Attempting to access properties of a Zdog element (`ref.current.rotate`) before the ref is assigned an instance or if the element is unmounted. This often happens with `useRef` and `useRender` if the Zdog element isn't properly initialized or is conditionally rendered.

fix

Ensure the ref is correctly attached to a `react-zdog` component and the component is mounted before attempting to access its properties. Use optional chaining (`ref.current?.rotate?.y`) or conditional checks (`if (ref.current)`) for safety.

Error: Invalid hook call. Hooks can only be called inside of the body of a function component.

A `react-zdog` hook (e.g., `useRender`, `useZdog`, `useInvalidate`) is being called outside of a functional React component, or inside a regular JavaScript function that isn't part of the component's render cycle, or outside the context of an `<Illustration>` component.

fix

Relocate the hook call to be directly within a functional React component that is rendered as a child of an `<Illustration>` component, or within a custom hook that respects React's rules of hooks.

Changes to Zdog object properties are not reflected on screen.

When the `<Illustration>` component has `frameloop='demand'`, direct mutations to Zdog objects (e.g., `boxRef.current.rotate.x += 0.03`) will update the underlying JavaScript object but will not trigger a re-render until `useInvalidate()` is explicitly called.

fix

After directly modifying Zdog object properties when `frameloop='demand'`, call the `invalidate()` function obtained from `useInvalidate()` to force a re-render of the scene.

Upgrade

Version history

1.2.2latest on npm

Audit

Dependencies

zdogrequiredCore pseudo 3D engine that react-zdog renders to.

reactrequiredFundamental library for building user interfaces, required by this React Fiber renderer.

Agent activity

22 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/drcmda/react-zdog ↗

packagehttps://www.npmjs.com/package/react-zdog ↗