openpencil/packages/pen-react

@zseven-w/pen-react

React UI SDK for OpenPencil — a complete set of hooks, components, and panels to build a design editor with React.

Install

npm install @zseven-w/pen-react
# or
bun add @zseven-w/pen-react

Peer dependencies: react@^19, react-dom@^19, @radix-ui/react-* (popover, select, separator, slider, switch, toggle, tooltip)

Overview

pen-react wraps @zseven-w/pen-engine into idiomatic React: a context provider, 10 semantic hooks, and 39 ready-to-use components covering the full editor UI.

<DesignProvider>
  <CoreToolbar />
  <DesignCanvas />
  <LayerPanel />
  <PropertyPanel />
  <PageTabs />
  <StatusBar />
</DesignProvider>

Quick Start

import {
  DesignProvider,
  DesignCanvas,
  CoreToolbar,
  LayerPanel,
  PropertyPanel,
} from '@zseven-w/pen-react';

function Editor() {
  return (
    <DesignProvider initialDocument={myDoc}>
      <div className="flex h-screen">
        <LayerPanel />
        <div className="flex flex-col flex-1">
          <CoreToolbar />
          <DesignCanvas className="flex-1" />
        </div>
        <PropertyPanel />
      </div>
    </DesignProvider>
  );
}

Hooks

All hooks subscribe to the engine and re-render on change:

import {
  useDesignEngine,
  useDocument,
  useSelection,
  useViewport,
  useActiveTool,
  useHistory,
  useActiveNode,
  useActivePage,
  useHover,
  useVariables,
} from '@zseven-w/pen-react';

function Inspector() {
  const node = useActiveNode(); // PenNode | null
  const selection = useSelection(); // string[]
  const { canUndo, undo } = useHistory();
  const viewport = useViewport(); // { zoom, panX, panY }
  const tool = useActiveTool(); // ToolType
  const doc = useDocument(); // PenDocument
  const page = useActivePage(); // PenPage
  const hoverId = useHover(); // string | null
  const variables = useVariables(); // VariableDefinition[]
  const engine = useDesignEngine(); // DesignEngine (escape hatch)

  return <div>Selected: {selection.length} nodes</div>;
}

Provider

Uncontrolled mode

Engine owns the document. Good for standalone editors:

<DesignProvider initialDocument={doc}>{children}</DesignProvider>

Controlled mode

Parent owns the document. Good for integration into existing state:

<DesignProvider document={doc} onDocumentChange={(newDoc) => setDoc(newDoc)}>
  {children}
</DesignProvider>

Echo-loop prevention is built in — onDocumentChange won't fire for changes that originated from the parent.

Components

Canvas

Component	Description
DesignCanvas	GPU-rendered canvas with CanvasKit/Skia. Handles zoom, pan, resize, and all interactions.

<DesignCanvas
  className="w-full h-full"
  onReady={(engine) => console.log('Canvas ready')}
  loadingFallback={<Spinner />}
/>

Toolbar

Component	Description
CoreToolbar	Main tool selection bar (select, frame, shapes, text, pen, image)
ToolButton	Individual tool button with icon + active state
ShapeToolDropdown	Dropdown for shape tools (rectangle, ellipse, polygon, line)
BooleanToolbar	Union, subtract, intersect, exclude operations

Panels

Component	Description
LayerPanel	Hierarchical tree view with drag-and-drop reordering
LayerItem	Single layer row — collapse, visibility, lock, rename
LayerContextMenu	Right-click menu: copy, paste, delete, group, z-order
PropertyPanel	Tabbed property inspector for the selected node
PageTabs	Multi-page tab bar with add/rename/reorder/delete
StatusBar	Bottom bar with zoom, coordinates, node count

Property Sections

Drop these into your own property panel or use PropertyPanel which includes all of them:

Section	Edits
SizeSection	x, y, width, height, rotation, constraints
FillSection	Solid color, linear/radial gradient
StrokeSection	Color, thickness, dash pattern, cap, join
TextSection	Font family, size, weight, color, alignment
TextLayoutSection	Line height, letter spacing, paragraph spacing
CornerRadiusSection	Uniform or per-corner border radius
EffectsSection	Drop shadow, inner shadow, blur
LayoutSection	Auto-layout direction, gap, justify, align
LayoutPaddingSection	Uniform or per-side padding
AppearanceSection	Opacity, blend mode
IconSection	Icon name picker (Lucide icons)
ImageSection	Image source, fit mode
ExportSection	Code generation target (React, HTML, Vue, etc.)

Shared UI

Component	Description
ColorPicker	Color input with swatch palette and hex input
NumberInput	Numeric field with drag-to-adjust and arrow keys
SectionHeader	Collapsible section header with title + actions
FontPicker	Font family selector with preview
VariablePicker	Design variable reference picker ($primary, etc.)
IconPickerDialog	Modal icon browser with search and categories

UI Store

Ephemeral UI state (panel open/close, drag state) managed by Zustand — separate from engine state:

import { useUIStore } from '@zseven-w/pen-react';

const { layerPanelOpen, toggleLayerPanel } = useUIStore();

Styling

Components use Tailwind CSS + CVA for variant styling, and Radix UI primitives for accessibility. Override styles via className props or Tailwind's design token system.

License

MIT