@somakine/react

A React component for the Somakine 3D anatomy viewer.

npm install @somakine/react react three

react and three are peer dependencies and must be installed by the host application.

import { useRef } from "react";
import { SomakineViewer, type SomakineViewerHandle } from "@somakine/react";
import { musculoskeletalBasic } from "@somakine/musculoskeletal-basic";

function Body() {
  const viewer = useRef<SomakineViewerHandle>(null);
  return (
    <SomakineViewer
      ref={viewer}
      dataset={musculoskeletalBasic}
      accessibleLabel="Interactive body model"
      onSelection={(selection) => console.log(selection.label)}
      onStateChange={(state) => console.log(state.phase, state.message)}
      style={{ height: "32rem" }}
    />
  );
}

The component owns the host element and the viewer's lifecycle (creation and disposal). The viewer owns the canvas, scene, semantic events, verified loading, and resource disposal. The host application still owns controls, navigation, labels, panels, and educational content.

Props

| Prop | Type | Notes | | --- | --- | --- | | dataset | DataPack | Required. Validated Somakine data pack. | | accessibleLabel | string | Required. Canvas aria-label. | | locale | string | Initial label language. Default "en". | | background | string \| null | Clear colour, or null for transparent. | | initialViewDirection | [number, number, number] | Initial camera direction. | | initialViewUp | [number, number, number] | Camera up axis. | | initialVisibleStructureIds | readonly StructureId[] | Initial semantic subset; with loading.mode: "visible", only this subset loads initially. | | loading | ViewerLoadingOptions | Demand-driven mode and asset concurrency. | | assetResolver | AssetResolver | Custom GLB byte resolver. | | onSelection | (selection) => void | Fires for a single selection. | | onSelectionGroup | (selections) => void | Fires for every selection change. | | onStateChange | (state) => void | Lifecycle state transitions. | | onAssetProgress | (progress) => void | Per-asset loading phases and aggregate progress. | | onStructureTransformChange | (change) => void | Structure offset changes from host calls or move-mode gestures. | | onError | (error) => void | Creation failure (not unmount). | | className | string | Host element class. | | style | CSSProperties | Host element style; must provide a height. |

Creation-time props (dataset, background, initialView*, initialVisibleStructureIds, loading, assetResolver, locale) are read when the viewer is created. To change them, remount the component — for example by changing its key.

Imperative handle

A ref exposes the viewer's imperative methods. They are no-ops until the viewer is ready (after onStateChange reports phase: "ready").

viewer.current?.setLocale("zh-CN");
viewer.current?.setInteractionMode("pan");
viewer.current?.selectStructure("somakine:structure:femur");
viewer.current?.focusRegion("somakine:region:knee");
viewer.current?.setExplode(0.5, { types: ["muscle"] });
viewer.current?.setInteractionMode("move");
viewer.current?.setLayerStyle("muscle", { opacity: 0.2, transparent: true });
viewer.current?.setLayerVisibility("muscle", false); // hide without reframing
function inspectPoint(clientX: number, clientY: number) {
  return viewer.current?.pickAt(clientX, clientY) ?? [];
}
await viewer.current?.preloadStructures(["somakine:structure:femur"]);
viewer.current?.reset(); // restore the complete creation-time scene state
viewer.current?.resetView(); // preserve the current semantic visibility

The handle also supports shared layer ghosting through setLayerStyle and occlusion-aware deep picking through pickAt. pickAt returns an empty array until the viewer is ready. setLayerVisibility hides a layer without loading or changing the camera, and restores only the current semantic visible subset. Hidden structures are excluded from normal picking, pickAt, and move-mode dragging.

setLayer, setVisible, focusRegion, and showBody clear highlighting without emitting a selection callback. reset and resetView clear highlighting and emit an empty onSelectionGroup callback. focusStructure is the selection-oriented exception: it isolates the target and emits its resolved selection.

API reference: docs/api/react.md