Hooks

All hooks are imported from @codecanon/waraq and must be used inside a <Waraq> provider.

useWaraqDocument

Returns layer operations and canvas layer state. Use this when you need to read or mutate layers.

import { useWaraqDocument } from "@codecanon/waraq"

function MyComponent() {
  const { layers, updateLayer, getLayer, addLayer, deleteSelected } = useWaraqDocument()
}

State

Property	Type	Description
`layers`	`Layer[]`	All layers in the current design
`layersHistory`	`HistoryState<Layer[]>`	Undo/redo history object

Layer methods

Method	Signature	Description
`addLayer`	`(type: string, data?: Partial<Layer>) => void`	Add a new layer
`updateLayer`	`({ id, ...partial }) => void`	Update a single layer
`updateLayers`	`(items[]) => void`	Batch update multiple layers
`getLayer`	`<T>(id: string) => Layer<T> \| undefined`	Get a layer by ID
`setLayers`	`(layers: Layer[]) => void`	Replace the entire layers array

Edit actions

Method	Description
`deleteSelected()`	Delete selected layers
`duplicate()`	Duplicate selected layers
`toggleVisibility()`	Show/hide selected layers
`bringToFront()`	Move selected layers to top
`sendToBack()`	Move selected layers to bottom
`toggleLock()`	Lock/unlock selected layers

useWaraqFrame

Returns canvas frame state: dimensions, background color, and the frame DOM ref. Use this when your component only cares about the canvas frame properties.

import { useWaraqFrame } from "@codecanon/waraq"

function FrameInfo() {
  const { frameSize, frameBackgroundColor, setFrameSize } = useWaraqFrame()

  return (
    <div>
      <span>{frameSize.width} × {frameSize.height}</span>
    </div>
  )
}

Return value

Property	Type	Description
`frameSize`	`FrameSize`	Canvas width and height in px
`frameBackgroundColor`	`string`	Canvas background color
`frameRef`	`RefObject<HTMLDivElement>`	The canvas frame DOM element
`setFrameSize`	`Dispatch<SetStateAction<FrameSize>>`	Resize the canvas frame
`setFrameBackgroundColor`	`Dispatch<SetStateAction<string>>`	Change canvas background

useWaraqTool

Returns the active tool and its setter. Prefer this hook over a broader hook when you only need to read or change the current tool — it avoids re-rendering on unrelated state changes.

import { useWaraqTool } from "@codecanon/waraq"

function Toolbar() {
  const { tool, setTool } = useWaraqTool()

  return (
    <button onClick={() => setTool("hand")}>
      {tool === "hand" ? "Hand active" : "Switch to hand"}
    </button>
  )
}

Return value

Property	Type	Description
`tool`	`Tool`	Active tool: `"select"` \| `"move"` \| `"hand"`
`setTool`	`Dispatch<SetStateAction<Tool>>`	Switch the active tool

useWaraqZoom

Returns zoom level and zoom action methods.

import { useWaraqZoom } from "@codecanon/waraq"

function ZoomControls() {
  const { zoom, zoomFit, zoom100 } = useWaraqZoom()

  return (
    <div>
      <span>Zoom: {Math.round(zoom * 100)}%</span>
      <button onClick={zoomFit}>Fit</button>
      <button onClick={zoom100}>100%</button>
    </div>
  )
}

Return value

Property	Type	Description
`zoom`	`number`	Current zoom level
`setZoom`	`Dispatch<SetStateAction<number>>`	Set zoom level directly
`zoomIn()`	`() => void`	Increase zoom by one step
`zoomOut()`	`() => void`	Decrease zoom by one step
`zoom100()`	`() => void`	Set zoom to 100%
`zoomFit()`	`() => void`	Fit canvas to viewport
`zoomAndCenter(zoom)`	`(zoom: number) => void`	Set zoom and scroll to center
`scrollCenter()`	`() => void`	Scroll to canvas center without changing zoom

useWaraqSelection

Returns selection state and selection control methods.

import { useWaraqSelection } from "@codecanon/waraq"

function SelectionInfo() {
  const { selectedLayerCount, unselectAll } = useWaraqSelection()

  return (
    <div>
      <span>{selectedLayerCount} selected</span>
      <button onClick={unselectAll}>Clear</button>
    </div>
  )
}

Return value

Property	Type	Description
`selectedLayerRefs`	`(HTMLElement \| SVGElement)[]`	DOM elements for selected layers
`selectedLayerCount`	`number`	Number of currently selected layers
`setSelectedTargets`	`(els[]) => Promise<void>`	Select by DOM elements
`getSelectedLayerIds`	`() => string[]`	IDs of currently selected layers
`select`	`(layerId: string) => Promise<void>`	Programmatically select a layer
`unselectAll`	`() => void`	Clear selection

useWaraqRefs

Returns stable DOM and library refs. These refs never change identity after mount.

import { useWaraqRefs } from "@codecanon/waraq"

function MyComponent() {
  const { viewerRef, moveableRef } = useWaraqRefs()
}

Return value

Ref	Type	Description
`contentRef`	`RefObject<HTMLDivElement>`	The editor content root element
`viewerRef`	`RefObject<InfiniteViewer>`	The pan/zoom viewer instance
`selectoRef`	`RefObject<Selecto>`	The multi-select instance
`moveableRef`	`RefObject<Moveable>`	The drag/resize handle instance

useWaraqConfig

Returns static configuration: editor instance ID, registered keyboard shortcuts, and layer type definitions.

import { useWaraqConfig } from "@codecanon/waraq"

function MyComponent() {
  const { id, layerTypes, keyboardShortcuts } = useWaraqConfig()
}

Return value

Property	Type	Description
`id`	`string`	Stable editor instance ID
`keyboardShortcuts`	`KeyboardShortcut[]`	Active keyboard shortcut definitions
`layerTypes`	`LayerType[]`	Registered layer type definitions

useWaraqDispatch

Returns a single action dispatcher for triggering editor actions imperatively.

import { useWaraqDispatch } from "@codecanon/waraq"

function MyButton() {
  const dispatch = useWaraqDispatch()

  return (
    <button onClick={() => dispatch("ZOOM_FIT")}>Fit canvas</button>
  )
}

The dispatcher accepts an ActionType string. See Types & constants — ActionType for all available action strings.

useWaraqAction

A focused hook for editing the currently selected layer's properties. Use this inside custom action components.

import { useWaraqAction } from "@codecanon/waraq"

function MyCustomAction() {
  const { layer, isMultiple, setLayer, getCSSVar, setCSSVar, setData, getData } =
    useWaraqAction<MyLayerData>()

  if (!layer) return null

  return (
    <input
      value={getCSSVar("--color", "#000000")}
      onChange={(e) => setCSSVar("--color", e.target.value)}
    />
  )
}

Return value

Property	Type	Description
`layer`	`Layer \| null`	The first selected layer (or `null` if nothing selected)
`isMultiple`	`boolean`	`true` when multiple layers are selected
`setLayer`	`(partial: Partial<Layer<T>>) => void`	Update the selected layer(s)
`getCSSVar`	`(varName, defaultValue?) => string`	Read a CSS variable from the selected layer
`setCSSVar`	`SetCSSVar`	Write a CSS variable to the selected layer(s)
`parseCSSValue`	`(varName, defaultValue?) => number`	Read a CSS variable as a number
`setData`	`<K>(key: K, value: T[K]) => void`	Write to the layer's custom `data` field
`getData`	`<K>(key: K, defaultValue?) => T[K]`	Read from the layer's custom `data` field

useWaraqDocumentAction

Read and write the canvas document properties (frame size and background color).

import { useWaraqDocumentAction } from "@codecanon/waraq"

function DocumentControls() {
  const { width, height, setWidth, setHeight, backgroundColor, setBackgroundColor } =
    useWaraqDocumentAction()

  return (
    <div>
      <input type="number" value={width} onChange={(e) => setWidth(+e.target.value)} />
      <input type="number" value={height} onChange={(e) => setHeight(+e.target.value)} />
    </div>
  )
}

Return value

Property	Type	Description
`width`	`number`	Canvas width in px
`height`	`number`	Canvas height in px
`setWidth`	`(width: number) => void`	Update canvas width
`setHeight`	`(height: number) => void`	Update canvas height
`backgroundColor`	`string`	Canvas background color
`setBackgroundColor`	`Dispatch<SetStateAction<string>>`	Update canvas background
`frameRef`	`RefObject<HTMLDivElement>`	Ref to the canvas frame DOM node

On this page