@grafloria/react

React bindings for Grafloria Diagrams and Grafloria Dashboards — an MIT diagram and dashboard engine: routing, auto-layout, undo, collaboration and dashboard layouts, native in React.

Install

bash
Copy
npm install @grafloria/react @grafloria/engine @grafloria/renderer react react-dom @grafloria/element

It expects these alongside it:

• @grafloria/engine ^0.3.0
• @grafloria/renderer ^0.4.16
• react ^17.0.0 || ^18.0.0 || ^19.0.0
• react-dom ^17.0.0 || ^18.0.0 || ^19.0.0
• @grafloria/element ^0.4.3

Functions

createGrafloriaStore

ts
Copy
function createGrafloriaStore(): GrafloriaStore

GrafloriaCommentPanel

ts
Copy
function GrafloriaCommentPanel(props: GrafloriaCommentPanelProps)

Props

Events

• onSelect

GrafloriaDashboard

ts
Copy
function GrafloriaDashboard(props: GrafloriaDashboardProps)

Props

Events

• onReady — The typed handle, once the board is live.
• onLayoutChange — Mirrors the kit's committed gestures (drag, resize, add, remove).

GrafloriaDiagram

ts
Copy
function GrafloriaDiagram(props: GrafloriaDiagramProps)

Props

Events

• onReady

GrafloriaFlow

ts
Copy
function GrafloriaFlow(props: GrafloriaFlowProps)

Props

Events

• onNodesChange
• onEdgesChange
• onSelectionChange
• onConnect
• onNodeClick
• onEdgeClick
• onInit
• onLayoutDone — Fires after each declarative layout completes.
• onCollabReady — The live SyncAdapter, right after join().

GrafloriaProvider

Wrap anything that needs useGrafloria() outside of <GrafloriaFlow>'s subtree.

tsx
Copy
<GrafloriaProvider>
  <Toolbar />           // useGrafloria() works here…
  <GrafloriaFlow … />       // …because the flow publishes its instance to the store
</GrafloriaProvider>

<GrafloriaFlow> also creates its own store when there is no provider, so the simple single-canvas case needs no wrapper at all.

ts
Copy
function GrafloriaProvider({ children }: GrafloriaProviderProps)

Props

useEdgesState

Controlled edge state. Mirrors {@link useNodesState}.

ts
Copy
function useEdgesState(initial: EdgeSpec[] = []): EdgesState

useGrafloria

The live DiagramInstance, or null until <GrafloriaFlow> has mounted.

Works from anywhere inside an <GrafloriaProvider> (a toolbar, a minimap, a sidebar) and from inside <GrafloriaFlow>'s own children.

tsx
Copy
const grafloria = useGrafloria();
<button onClick={() => grafloria?.fitView()}>Fit</button>

ts
Copy
function useGrafloria(): DiagramInstance | null

useGrafloriaStore

The nearest store, or null when there is no provider above us.

ts
Copy
function useGrafloriaStore(): GrafloriaStore | null

useNodesState

Controlled node state — the React Flow tuple everyone already knows:

tsx
Copy
const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes);
<GrafloriaFlow nodes={nodes} onNodesChange={onNodesChange} … />

onNodesChange is what closes the loop: the user drags a node, the ENGINE moves it, the instance emits nodes:change, <GrafloriaFlow> calls this, and React state catches up. Without it a controlled <GrafloriaFlow> would snap the node back on the next render — the classic controlled-component trap.

ts
Copy
function useNodesState(initial: NodeSpec[] = []): NodesState

useOnSelectionChange

Fire a callback whenever the selection changes.

tsx
Copy
useOnSelectionChange(({ nodes }) => setInspected(nodes[0] ?? null));

The handler is held in a ref, so passing an inline arrow (the common case) does NOT re-subscribe on every render.

ts
Copy
function useOnSelectionChange(handler: (change: SelectionChange) => void): void

useSelection

The current selection as state (for rendering an inspector panel).

ts
Copy
function useSelection(): SelectionChange

useViewport

The live camera (zoom + world rect) as state — for a minimap or a zoom badge.

ts
Copy
function useViewport(): { zoom: number; x: number; y: number }

Constants

GrafloriaContext

ts
Copy
const GrafloriaContext: any

Interfaces

GrafloriaCommentPanelProps

ts
Copy
interface GrafloriaCommentPanelProps

Properties

GrafloriaDashboardProps

ts
Copy
interface GrafloriaDashboardProps

Properties

GrafloriaDiagramProps

ts
Copy
interface GrafloriaDiagramProps

Properties

GrafloriaFlowProps

ts
Copy
interface GrafloriaFlowProps

Properties

GrafloriaProviderProps

ts
Copy
interface GrafloriaProviderProps

Properties

GrafloriaStore

The provider + the store behind useGrafloria().

React Flow's ergonomics come from exactly this shape: a <ReactFlowProvider> that lets a toolbar, a sidebar or a minimap — components that are SIBLINGS of the canvas, not children of it — reach the live instance. We keep that shape, but the thing being shared is our framework-agnostic DiagramInstance, so the provider is a 40-line store and NOT a re-implementation of the diagram.

Why a hand-rolled store rather than useSyncExternalStore: that hook is React 18+, and this package supports React 17–19. Subscribe + useState costs one extra render on attach and works everywhere.

ts
Copy
interface GrafloriaStore

Members

• get(): DiagramInstance | null — The live instance, or null before <GrafloriaFlow> has mounted.
• set(instance: DiagramInstance | null): void — Called by <GrafloriaFlow> on mount/unmount.
• subscribe(listener: (instance: DiagramInstance | null) => void): () => void — Notified whenever the instance is attached or detached.

NodeProps

Props a custom node component receives. Deliberately React-Flow-shaped.

ts
Copy
interface NodeProps<TData = Record<string, unknown>>

Properties

SelectionChange

ts
Copy
interface SelectionChange

Properties

WidgetProps

Props a widget component receives — the NodeProps twin for boards.

ts
Copy
interface WidgetProps<TData = Record<string, unknown>>

Properties

Types

EdgesState

ts
Copy
type EdgesState = [
  EdgeSpec[],
  Dispatch<SetStateAction<EdgeSpec[]>>,
  (edges: LinkModel[]) => void,
];

NodesState

What useNodesState hands back — React Flow's tuple, with our types.

ts
Copy
type NodesState = [
  NodeSpec[],
  Dispatch<SetStateAction<NodeSpec[]>>,
  (nodes: NodeModel[]) => void,
];

NodeTypes

nodeTypes maps a node's type to the component that renders it.

ts
Copy
type NodeTypes = Record<string, ComponentType<NodeProps<never>>>;

WidgetTypes

ts
Copy
type WidgetTypes = Record<string, ComponentType<WidgetProps>>;

Also exported from here

These names are documented with the package that defines them, and can be imported from this one too.

• From @grafloria/renderer: DARK_THEME, DiagramInstance, EdgeSpec, HydrationSnapshot, LIGHT_THEME, NodeSpec, PortSpec, renderToStaticSVG, StaticRenderOptions, StaticRenderResult, Theme