diff --git a/packages/joint-react/stories/examples/measured-state/code.tsx b/packages/joint-react/stories/examples/measured-state/code.tsx
new file mode 100644
index 0000000000..cff47f03d3
--- /dev/null
+++ b/packages/joint-react/stories/examples/measured-state/code.tsx
@@ -0,0 +1,264 @@
+/* eslint-disable react-perf/jsx-no-new-function-as-prop */
+/* eslint-disable sonarjs/pseudo-random -- picks a demo node to resize, not security-sensitive */
+import { useRef, useState, type ReactNode } from 'react';
+import type { dia } from '@joint/core';
+import {
+ GraphProvider,
+ HTMLBox,
+ Paper,
+ useCells,
+ useGraph,
+ useOnCellsChange,
+ selectIsMeasured,
+ selectMeasuredState,
+ selectElementsSizes,
+ type CellRecord,
+ type ElementRecord,
+} from '@joint/react';
+
+interface NodeData {
+ readonly label: string;
+ readonly isLong?: boolean;
+}
+
+const GAP = 24;
+const ROW_WIDTH = 560;
+const LOG_LIMIT = 9;
+const LONG_SUFFIX = ' · with a much longer label';
+
+const initialCells: ReadonlyArray
> = [
+ { id: 'n1', type: 'element', data: { label: 'Node 1' }, position: { x: GAP, y: GAP } },
+ { id: 'n2', type: 'element', data: { label: 'Node 2' }, position: { x: 140, y: GAP } },
+ { id: 'n3', type: 'element', data: { label: 'Node 3' }, position: { x: 260, y: GAP } },
+];
+
+/** Flows the elements left to right by their measured width, wrapping at `ROW_WIDTH`. */
+function layoutRows(graph: dia.Graph) {
+ let x = GAP;
+ let y = GAP;
+ let rowHeight = 0;
+ for (const element of graph.getElements()) {
+ const { width, height } = element.size();
+ if (x > GAP && x + width > ROW_WIDTH) {
+ x = GAP;
+ y += rowHeight + GAP;
+ rowHeight = 0;
+ }
+ element.position(x, y);
+ x += width + GAP;
+ rowHeight = Math.max(rowHeight, height);
+ }
+}
+
+function renderElement({ label, isLong }: NodeData) {
+ // No size on the records: HTMLBox measures its content and writes the size back.
+ return {isLong ? label + LONG_SUFFIX : label};
+}
+
+type Source = 'isMeasured' | 'measuredState' | 'sizes';
+
+interface LogEntry {
+ readonly id: number;
+ readonly source: Source;
+ readonly text: string;
+}
+
+const SOURCE_CLASS: Record = {
+ isMeasured: 'text-brand',
+ measuredState: 'text-accent',
+ sizes: 'text-ink',
+};
+
+/**
+ * Logs every change of the three measurement selectors. `useOnCellsChange`
+ * calls back without re-rendering this component; only the log state does.
+ */
+function useMeasurementLog(isAutoLayout: boolean) {
+ const { graph } = useGraph();
+ const [entries, setEntries] = useState([]);
+ const nextIdRef = useRef(0);
+
+ const log = (source: Source, text: string) => {
+ nextIdRef.current += 1;
+ const entry = { id: nextIdRef.current, source, text };
+ setEntries((previous) => [entry, ...previous].slice(0, LOG_LIMIT));
+ };
+
+ // 1. Once per diagram: false → true when the sizes first settle.
+ useOnCellsChange(selectIsMeasured, (isMeasured, previous) => {
+ log(
+ 'isMeasured',
+ previous === undefined ? `${isMeasured} (mount)` : `${previous} → ${isMeasured}`
+ );
+ });
+
+ // 2. Every settled change: first pass, add, remove, re-measure. The place to run a layout.
+ useOnCellsChange(selectMeasuredState, (measuredState) => {
+ log('measuredState', measuredState ? `settled #${measuredState}` : '0 (nothing measured)');
+ if (measuredState && isAutoLayout) layoutRows(graph);
+ });
+
+ // 3. Any size change, element by element. Moving elements never fires it.
+ useOnCellsChange(selectElementsSizes, (sizes, previous) => {
+ let changed = 0;
+ let kept = 0;
+ for (const [id, { width, height }] of sizes) {
+ const before = previous?.get(id);
+ if (before) kept += 1;
+ if (before?.width !== width || before.height !== height) changed += 1;
+ }
+ const removed = (previous?.size ?? 0) - kept;
+ log('sizes', removed > 0 ? `${removed} removed` : `${changed} of ${sizes.size} changed`);
+ });
+
+ return entries;
+}
+
+function Controls({ onMove }: Readonly<{ onMove: () => void }>) {
+ const { graph, setCell, setCellData, removeCell, resetCells } =
+ useGraph>();
+ const nextIdRef = useRef(initialCells.length);
+
+ const addNode = () => {
+ nextIdRef.current += 1;
+ const id = `n${nextIdRef.current}`;
+ setCell({ id, type: 'element', data: { label: `Node ${nextIdRef.current}` } });
+ };
+
+ const removeLast = () => {
+ const last = graph.getElements().at(-1);
+ if (last) removeCell(last);
+ };
+
+ const toggleLabel = () => {
+ const elements = graph.getElements();
+ const element = elements[Math.floor(Math.random() * elements.length)];
+ if (!element) return;
+ setCellData(element.id, (previous) => ({ ...previous, isLong: !previous.isLong }));
+ };
+
+ const moveAll = () => {
+ for (const element of graph.getElements()) element.translate(0, GAP);
+ onMove();
+ };
+
+ return (
+
+
+
+
+
+
+
+
+ );
+}
+
+function SizesTable() {
+ // Same map reference until a size changes, so dragging does not re-render this.
+ const sizes = useCells(selectElementsSizes);
+ if (sizes.size === 0) return No elements.
;
+ return (
+
+ {[...sizes].map(([id, { width, height }]) => (
+ -
+ {id}
+
+ {Math.round(width)} × {Math.round(height)}
+
+
+ ))}
+
+ );
+}
+
+function Section({ title, children }: Readonly<{ title: string; children: ReactNode }>) {
+ return (
+
+ );
+}
+
+function Inspector({ entries, moves }: Readonly<{ entries: readonly LogEntry[]; moves: number }>) {
+ const isMeasured = useCells(selectIsMeasured);
+ const measuredState = useCells(selectMeasuredState);
+ return (
+
+ );
+}
+
+function Main() {
+ const [isAutoLayout, setIsAutoLayout] = useState(true);
+ const [moves, setMoves] = useState(0);
+ const entries = useMeasurementLog(isAutoLayout);
+
+ return (
+
+ );
+}
+
+export default function App() {
+ return (
+
+
+
+ );
+}
diff --git a/packages/joint-react/stories/examples/measured-state/story.tsx b/packages/joint-react/stories/examples/measured-state/story.tsx
new file mode 100644
index 0000000000..427174dac9
--- /dev/null
+++ b/packages/joint-react/stories/examples/measured-state/story.tsx
@@ -0,0 +1,25 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { getAPILink } from '../../utils/get-api-documentation-link';
+import Code from './code';
+import codeRaw from './code?raw';
+
+const meta = {
+ title: 'Examples/Measured state',
+ component: Code,
+ tags: ['example'],
+ parameters: {
+ showcase: {
+ description:
+ 'Watch selectIsMeasured flip once on load, selectMeasuredState change on every settled add, remove or re-measure, and selectElementsSizes change only when a size does. Moving nodes fires nothing.',
+ apiUrl: getAPILink('useOnCellsChange'),
+ code: codeRaw,
+ canvasHeight: 480,
+ },
+ },
+} satisfies Meta;
+
+export default meta;
+
+export type Story = StoryObj;
+
+export const Default: Story = {};