⚛️ ReactAPI Reference

API Reference

Complete reference for all exports from @canvus/react.

Components

<Canvus />

The primary workspace component. Creates a container <div>, initializes the @canvus/core Workspace engine, and provides context to child components.

import { Canvus } from "@canvus/react";
 
<Canvus
  config={{ snapThreshold: 8 }}
  onReactNodeCommit={(id, snapshot) => { /* ... */ }}
  onHTMLCommit={(id, html) => { /* ... */ }}
  onSelectionChange={(ids) => { /* ... */ }}
  style={{ width: "100%", height: "100vh" }}
  className="my-workspace"
  ref={canvusRef}
>
  {/* Child components can use useCanvus() */}
</Canvus>

Props

PropTypeDescription
configWorkspaceConfigWorkspace configuration (snap threshold, overlay styles)
styleCSSPropertiesCSS styles for the container div
classNamestringCSS class name for the container div
onHTMLCommit(id, html) => voidFired for vanilla HTML node commits only
onReactNodeCommit(id, snapshot) => voidFired for React node commits (drag/resize)
onSelectionChange(ids) => voidFired when selection changes
onViewportChange(viewport) => voidFired on pan/zoom
onOperationsGenerated(ops) => voidFired when undoable operations are produced
onNodeRectChange(id, rect) => voidFired when a node’s bounds change
onInteractionChange(mode) => voidFired when interaction mode changes
onBreadcrumbChange(path) => voidFired when selection hierarchy changes
onTextEditRequest(nodeId, el, commit) => voidFired for inline text editing
refRef<CanvusHandle>Imperative handle for direct access
childrenReactNodeChild components (can use useCanvus())

Ref Handle (CanvusHandle)

When you pass a ref to <Canvus />, you get a CanvusHandle with the same shape as the useCanvus() return value:

const canvusRef = useRef<CanvusHandle>(null);
 
// Later:
canvusRef.current?.addReactNode({ ... });
canvusRef.current?.workspace?.selectNode("node-1");

Hooks

useCanvus()

Returns the workspace context from the nearest <Canvus /> ancestor.

import { useCanvus } from "@canvus/react";
 
function MyComponent() {
  const {
    workspace,
    addReactNode,
    updateReactNode,
    removeReactNode,
    addNode,
  } = useCanvus();
 
  // ...
}

Throws an error if called outside of a <Canvus /> component tree.

Return Type: CanvusContextValue

PropertyTypeDescription
workspaceWorkspace | nullThe raw @canvus/core Workspace instance (null before mount)
addReactNode(descriptor) => voidMount a React component as a canvas node
updateReactNode(id, props) => voidUpdate props and re-render a React node
removeReactNode(id) => voidUnmount and remove a React node
addNode(node, parentId?, index?) => RectAdd a vanilla HTML node (pass-through to core)

Types

ReactNodeDescriptor

Describes a React component to mount on the canvas.

interface ReactNodeDescriptor {
  /** Unique node identifier. */
  id: string;
  /** The React component to render. */
  component: ComponentType<any>;
  /** Props to pass to the component. */
  props: Record<string, any>;
  /** Initial position and dimensions in canvas-space. */
  currentRect: Rect;
  /** Optional parent node ID for nested mounting. */
  parentId?: string | null;
}

ReactNodeSnapshot

Emitted via onReactNodeCommit when a React node is committed after a visual gesture.

interface ReactNodeSnapshot {
  /** The React component reference. */
  component: ComponentType<any>;
  /** String name of the component (for serialization). */
  componentName: string;
  /** Current props at the time of commit. */
  props: Record<string, any>;
  /** Current canvas-space bounding rect. */
  rect: Rect;
}

The componentName is derived from Component.displayName || Component.name. Set displayName on your components for reliable serialization:

function DashboardCard(props) { /* ... */ }
DashboardCard.displayName = "DashboardCard";

CanvusProps

Props accepted by the <Canvus /> component. See the Props table above for full details.

CanvusHandle

Type alias for the imperative ref handle, identical to CanvusContextValue.

Advanced: CanvusProvider & CanvusContext

For advanced use cases where you need to separate the container div from the context provider, both are exported:

import { CanvusProvider, CanvusContext } from "@canvus/react";

In most cases, the <Canvus /> component handles this for you and these exports are not needed.

Quick StartOperations & Undo/Redo