@vkcha/svg-core-react

React components for @vkcha/svg-core.

Live demo & docs: vkcha.com/#docs

Install

npm i @vkcha/svg-core @vkcha/svg-core-react react react-dom

Components

PanZoomCanvasView (pan/zoom only)

Lightweight pan/zoom canvas for custom SVG content.

import { useRef } from "react";
import { PanZoomCanvasView } from "@vkcha/svg-core-react";
import type { PanZoomCanvasViewHandle } from "@vkcha/svg-core-react";

export function CanvasOnly() {
  const viewRef = useRef<PanZoomCanvasViewHandle>(null);

  return (
    <PanZoomCanvasView
      ref={viewRef}
      options={{ wheelMode: "pan", minZoom: 0.5, maxZoom: 4 }}
      onReady={(canvas) => console.log("Canvas ready:", canvas)}
      style={{ width: "100%", height: "100%" }}
    >
      {/* Children render inside the pan/zoom world */}
      <rect x={0} y={0} width={100} height={50} fill="#3b82f6" />
    </PanZoomCanvasView>
  );
}

Props

| Prop | Type | Description | | ------------- | --------------------------------- | -------------------------------------------------------- | | options | Partial<PanZoomOptions> | Pan/zoom configuration | | onReady | (canvas: PanZoomCanvas) => void | Called after canvas is constructed | | onDestroy | (canvas: PanZoomCanvas) => void | Called before cleanup on unmount | | autoDestroy | boolean | If true (default), calls canvas.destroy() on unmount | | children | ReactNode | Rendered into the pan/zoom world layer | | ...svgProps | SVGProps<SVGSVGElement> | Passed to the root <svg> |

Ref Handle (PanZoomCanvasViewHandle)

viewRef.current?.getSvg(); // SVGSVGElement
viewRef.current?.getCanvas(); // PanZoomCanvas instance
viewRef.current?.getWorld(); // SVGGElement (world layer)
viewRef.current?.getChildrenLayer(); // SVGGElement (React children layer)

SvgCoreView (nodes + culling + hit-testing)

Full scene management with nodes as React props.

import { useMemo, useRef } from "react";
import { SvgCoreView } from "@vkcha/svg-core-react";
import type { SvgCoreViewHandle, NodeOptions } from "@vkcha/svg-core-react";

export function Scene() {
  const coreRef = useRef<SvgCoreViewHandle>(null);

  // Memoize nodes to prevent unnecessary re-renders
  const nodes = useMemo<NodeOptions[]>(
    () => [
      {
        id: "node-1",
        x: 0,
        y: 0,
        fragment: `<rect width="120" height="60" rx="8" fill="#10b981" />`,
      },
    ],
    [],
  );

  return (
    <SvgCoreView
      ref={coreRef}
      nodes={nodes}
      init={{
        panZoom: { wheelMode: "pan" },
        culling: { enabled: true, overscanPx: 50 },
      }}
      onReady={(core) => console.log("SvgCore ready:", core)}
      style={{ width: "100%", height: "100%" }}
    />
  );
}

Props

| Prop | Type | Description | | ------------- | ------------------------- | ------------------------------------------------------ | | init | InitOptions | SvgCore init options (panZoom + culling) | | nodes | (Node \| NodeOptions)[] | Nodes to render; undefined = unchanged, [] = clear | | onReady | (core: SvgCore) => void | Called after SvgCore is constructed | | onDestroy | (core: SvgCore) => void | Called before cleanup on unmount | | children | ReactNode | Rendered into the pan/zoom world layer | | ...svgProps | SVGProps<SVGSVGElement> | Passed to the root <svg> |

Ref Handle (SvgCoreViewHandle)

coreRef.current?.getSvg(); // SVGSVGElement
coreRef.current?.getCanvas(); // PanZoomCanvas instance
coreRef.current?.getCore(); // SvgCore instance

Children Rendering

React children are rendered inside the pan/zoom world layer. Special SVG elements (<defs>, <style>, <title>, <desc>, <metadata>) are automatically hoisted to the SVG root.

<PanZoomCanvasView options={{ wheelMode: "pan" }}>
  {/* These pan/zoom with the canvas */}
  <rect x={0} y={0} width={100} height={50} fill="#3b82f6" />
  <circle cx={150} cy={25} r={20} fill="#10b981" />

  {/* Hoisted to SVG root */}
  <defs>
    <linearGradient id="grad1">...</linearGradient>
  </defs>
</PanZoomCanvasView>

Re-exported Types

Common types are re-exported for convenience:

import type {
  PanZoomState,
  PanZoomOptions,
  PanZoomWheelMode,
  WorldGroupConfig,
  InitOptions,
  CullingOptions,
  CullingStats,
  NodeOptions,
  NodeId,
  WorldLayerPosition,
} from "@vkcha/svg-core-react";

See Also

• @vkcha/svg-core — Core vanilla library
• Live Demo — Interactive playground
• Documentation — Full API reference