Merge pull request #5010 from xyflow/tsdocs-update

TSDoc update

packages/react/src/hooks/useConnection.ts

@@ -24,9 +24,28 @@ function getSelector<NodeType extends Node = Node, SelectorReturn = ConnectionSt
   return storeSelector;
 }
 /**
- * Hook for accessing the connection state.
+ * The `useConnection` hook returns the current connection when there is an active
+ * connection interaction. If no connection interaction is active, it returns null
+ * for every property. A typical use case for this hook is to colorize handles
+ * based on a certain condition (e.g. if the connection is valid or not).
  *
  * @public
+ * @example
+ *
+ * ```tsx
+ *import { useConnection } from '@xyflow/react';
+ *
+ *function App() {
+ *  const connection = useConnection();
+ *
+ *  return (
+ *    <div> {connection ? `Someone is trying to make a connection from ${connection.fromNode} to this one.` : 'There are currently no incoming connections!'}
+ *
+ *   </div>
+ *   );
+ * }
+ * ```
+ *
  * @returns ConnectionState
  */
 export function useConnection<NodeType extends Node = Node, SelectorReturn = ConnectionState<InternalNode<NodeType>>>(

packages/react/src/hooks/useEdges.ts

@@ -6,10 +6,22 @@ import type { Edge, ReactFlowState } from '../types';
 const edgesSelector = (state: ReactFlowState) => state.edges;
 
 /**
- * Hook for getting the current edges from the store.
+ * This hook returns an array of the current edges. Components that use this hook
+ * will re-render **whenever any edge changes**.
  *
  * @public
  * @returns An array of edges
+ *
+ * @example
+ * ```tsx
+ *import { useEdges } from '@xyflow/react';
+ *
+ *export default function () {
+ *  const edges = useEdges();
+ *
+ *  return <div>There are currently {edges.length} edges!</div>;
+ *}
+ *```
  */
 export function useEdges<EdgeType extends Edge = Edge>(): EdgeType[] {
   const edges = useStore(edgesSelector, shallow) as EdgeType[];

packages/react/src/hooks/useInternalNode.ts

@@ -5,11 +5,31 @@ import { useStore } from './useStore';
 import type { InternalNode, Node } from '../types';
 
 /**
- * Hook for getting an internal node by id
+ * This hook returns the internal representation of a specific node.
+ * Components that use this hook will re-render **whenever the node changes**,
+ * including when a node is selected or moved.
  *
  * @public
  * @param id - id of the node
  * @returns array with visible node ids
+ *
+ * @example
+ * ```tsx
+ *import { useInternalNode } from '@xyflow/react';
+ *
+ *export default function () {
+ *  const internalNode = useInternalNode('node-1');
+ *  const absolutePosition = internalNode.internals.positionAbsolute;
+ *
+ *  return (
+ *    <div>
+ *      The absolute position of the node is at:
+ *      <p>x: {absolutePosition.x}</p>
+ *      <p>y: {absolutePosition.y}</p>
+ *    </div>
+ *  );
+ *}
+ *```
  */
 export function useInternalNode<NodeType extends Node = Node>(id: string): InternalNode<NodeType> | undefined {
   const node = useStore(

packages/react/src/hooks/useKeyPress.ts

@@ -13,18 +13,38 @@ export type UseKeyPressOptions = {
 const defaultDoc = typeof document !== 'undefined' ? document : null;
 
 /**
- * Hook for handling key events.
+ * This hook lets you listen for specific key codes and tells you whether they are
+ * currently pressed or not.
  *
  * @public
  * @param param.keyCode - The key code (string or array of strings) to use
  * @param param.options - Options
  * @returns boolean
+ *
+ * @example
+ * ```tsx
+ *import { useKeyPress } from '@xyflow/react';
+ *
+ *export default function () {
+ *  const spacePressed = useKeyPress('Space');
+ *  const cmdAndSPressed = useKeyPress(['Meta+s', 'Strg+s']);
+ *
+ *  return (
+ *    <div>
+ *     {spacePressed && <p>Space pressed!</p>}
+ *     {cmdAndSPressed && <p>Cmd + S pressed!</p>}
+ *    </div>
+ *  );
+ *}
+ *```
  */
 export function useKeyPress(
-  // the keycode can be a string 'a' or an array of strings ['a', 'a+d']
-  // a string means a single key 'a' or a combination when '+' is used 'a+d'
-  // an array means different possibilites. Explainer: ['a', 'd+s'] here the
-  // user can use the single key 'a' or the combination 'd' + 's'
+  /*
+   * the keycode can be a string 'a' or an array of strings ['a', 'a+d']
+   * a string means a single key 'a' or a combination when '+' is used 'a+d'
+   * an array means different possibilites. Explainer: ['a', 'd+s'] here the
+   * user can use the single key 'a' or the combination 'd' + 's'
+   */
   keyCode: KeyCode | null = null,
   options: UseKeyPressOptions = { target: defaultDoc, actInsideInputWithModifier: true }
 ): boolean {
@@ -36,20 +56,24 @@ export function useKeyPress(
   // we need to remember the pressed keys in order to support combinations
   const pressedKeys = useRef<PressedKeys>(new Set([]));
 
-  // keyCodes = array with single keys [['a']] or key combinations [['a', 's']]
-  // keysToWatch = array with all keys flattened ['a', 'd', 'ShiftLeft']
-  // used to check if we store event.code or event.key. When the code is in the list of keysToWatch
-  // we use the code otherwise the key. Explainer: When you press the left "command" key, the code is "MetaLeft"
-  // and the key is "Meta". We want users to be able to pass keys and codes so we assume that the key is meant when
-  // we can't find it in the list of keysToWatch.
+  /*
+   * keyCodes = array with single keys [['a']] or key combinations [['a', 's']]
+   * keysToWatch = array with all keys flattened ['a', 'd', 'ShiftLeft']
+   * used to check if we store event.code or event.key. When the code is in the list of keysToWatch
+   * we use the code otherwise the key. Explainer: When you press the left "command" key, the code is "MetaLeft"
+   * and the key is "Meta". We want users to be able to pass keys and codes so we assume that the key is meant when
+   * we can't find it in the list of keysToWatch.
+   */
   const [keyCodes, keysToWatch] = useMemo<[Array<Keys>, Keys]>(() => {
     if (keyCode !== null) {
       const keyCodeArr = Array.isArray(keyCode) ? keyCode : [keyCode];
       const keys = keyCodeArr
         .filter((kc) => typeof kc === 'string')
-        // we first replace all '+' with '\n'  which we will use to split the keys on
-        // then we replace '\n\n' with '\n+', this way we can also support the combination 'key++'
-        // in the end we simply split on '\n' to get the key array
+        /*
+         * we first replace all '+' with '\n'  which we will use to split the keys on
+         * then we replace '\n\n' with '\n+', this way we can also support the combination 'key++'
+         * in the end we simply split on '\n' to get the key array
+         */
         .map((kc) => kc.replace('+', '\n').replace('\n\n', '\n+').split('\n'));
       const keysFlat = keys.reduce((res: Keys, item) => res.concat(...item), []);
 
@@ -133,12 +157,16 @@ export function useKeyPress(
 function isMatchingKey(keyCodes: Array<Keys>, pressedKeys: PressedKeys, isUp: boolean): boolean {
   return (
     keyCodes
-      // we only want to compare same sizes of keyCode definitions
-      // and pressed keys. When the user specified 'Meta' as a key somewhere
-      // this would also be truthy without this filter when user presses 'Meta' + 'r'
+      /*
+       * we only want to compare same sizes of keyCode definitions
+       * and pressed keys. When the user specified 'Meta' as a key somewhere
+       * this would also be truthy without this filter when user presses 'Meta' + 'r'
+       */
       .filter((keys) => isUp || keys.length === pressedKeys.size)
-      // since we want to support multiple possibilities only one of the
-      // combinations need to be part of the pressed keys
+      /*
+       * since we want to support multiple possibilities only one of the
+       * combinations need to be part of the pressed keys
+       */
       .some((keys) => keys.every((k) => pressedKeys.has(k)))
   );
 }

packages/react/src/hooks/useMoveSelectedNodes.ts

@@ -22,8 +22,10 @@ export function useMoveSelectedNodes() {
     const nodeUpdates = new Map();
     const isSelected = selectedAndDraggable(nodesDraggable);
 
-    // by default a node moves 5px on each key press
-    // if snap grid is enabled, we use that for the velocity
+    /*
+     * by default a node moves 5px on each key press
+     * if snap grid is enabled, we use that for the velocity
+     */
     const xVelo = snapToGrid ? snapGrid[0] : 5;
     const yVelo = snapToGrid ? snapGrid[1] : 5;
 

packages/react/src/hooks/useNodeConnections.ts

@@ -22,7 +22,7 @@ type UseNodeConnectionsParams = {
 };
 
 /**
- * Hook to retrieve all edges connected to a node. Can be filtered by handle type and id.
+ * This hook returns an array of connections on a specific node, handle type ('source', 'target') or handle ID.
  *
  * @public
  * @param param.id - node id - optional if called inside a custom node
@@ -31,6 +31,22 @@ type UseNodeConnectionsParams = {
  * @param param.onConnect - gets called when a connection is established
  * @param param.onDisconnect - gets called when a connection is removed
  * @returns an array with connections
+ *
+ * @example
+ * ```jsx
+ *import { useNodeConnections } from '@xyflow/react';
+ *
+ *export default function () {
+ *  const connections = useNodeConnections({
+ *    type: 'target',
+ *    handleId: 'my-handle',
+ *  });
+ *
+ *  return (
+ *    <div>There are currently {connections.length} incoming connections!</div>
+ *  );
+ *}
+ *```
  */
 export function useNodeConnections({
   id,

packages/react/src/hooks/useNodes.ts

@@ -6,10 +6,23 @@ import type { Node, ReactFlowState } from '../types';
 const nodesSelector = (state: ReactFlowState) => state.nodes;
 
 /**
- * Hook for getting the current nodes from the store.
+ * This hook returns an array of the current nodes. Components that use this hook
+ * will re-render **whenever any node changes**, including when a node is selected
+ * or moved.
  *
  * @public
  * @returns An array of nodes
+ *
+ * @example
+ * ```jsx
+ *import { useNodes } from '@xyflow/react';
+ *
+ *export default function() {
+ *  const nodes = useNodes();
+ *
+ *  return <div>There are currently {nodes.length} nodes!</div>;
+ *}
+ *```
  */
 export function useNodes<NodeType extends Node = Node>(): NodeType[] {
   const nodes = useStore(nodesSelector, shallow) as NodeType[];

packages/react/src/hooks/useNodesData.ts

@@ -5,12 +5,24 @@ import { useStore } from '../hooks/useStore';
 import type { Node } from '../types';
 
 /**
- * Hook for receiving data of one or multiple nodes
+ * This hook lets you subscribe to changes of a specific nodes `data` object.
  *
  * @public
  * @param nodeId - The id (or ids) of the node to get the data from
- * @param guard - Optional guard function to narrow down the node type
  * @returns An object (or array of object) with {id, type, data} representing each node
+ *
+ * @example
+ *
+ *```jsx
+ *import { useNodesData } from '@xyflow/react';
+ *
+ *export default function() {
+ *  const nodeData = useNodesData('nodeId-1');
+ *  const nodesData = useNodesData(['nodeId-1', 'nodeId-2']);
+ *
+ *  return null;
+ *}
+ *```
  */
 export function useNodesData<NodeType extends Node = Node>(
   nodeId: string

packages/react/src/hooks/useNodesEdgesState.ts

@@ -4,11 +4,41 @@ import { applyNodeChanges, applyEdgeChanges } from '../utils/changes';
 import type { Node, Edge, OnNodesChange, OnEdgesChange } from '../types';
 
 /**
- * Hook for managing the state of nodes - should only be used for prototyping / simple use cases.
+ * This hook makes it easy to prototype a controlled flow where you manage the
+ * state of nodes and edges outside the `ReactFlowInstance`. You can think of it
+ * like React's `useState` hook with an additional helper callback.
  *
  * @public
  * @param initialNodes
  * @returns an array [nodes, setNodes, onNodesChange]
+ * @example
+ *
+ *```tsx
+ *import { ReactFlow, useNodesState, useEdgesState } from '@xyflow/react';
+ *
+ *const initialNodes = [];
+ *const initialEdges = [];
+ *
+ *export default function () {
+ *  const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes);
+ *  const [edges, setEdges, onEdgesChange] = useEdgesState(initialEdges);
+ *
+ *  return (
+ *    <ReactFlow
+ *      nodes={nodes}
+ *      edges={edges}
+ *      onNodesChange={onNodesChange}
+ *      onEdgesChange={onEdgesChange}
+ *    />
+ *  );
+ *}
+ *```
+ *
+ * @remarks This hook was created to make prototyping easier and our documentation
+ * examples clearer. Although it is OK to use this hook in production, in
+ * practice you may want to use a more sophisticated state management solution
+ * like Zustand {@link https://reactflow.dev/docs/guides/state-management/} instead.
+ *
  */
 export function useNodesState<NodeType extends Node>(
   initialNodes: NodeType[]
@@ -23,11 +53,41 @@ export function useNodesState<NodeType extends Node>(
 }
 
 /**
- * Hook for managing the state of edges - should only be used for prototyping / simple use cases.
+ * This hook makes it easy to prototype a controlled flow where you manage the
+ * state of nodes and edges outside the `ReactFlowInstance`. You can think of it
+ * like React's `useState` hook with an additional helper callback.
  *
  * @public
  * @param initialEdges
  * @returns an array [edges, setEdges, onEdgesChange]
+ * @example
+ *
+ *```tsx
+ *import { ReactFlow, useNodesState, useEdgesState } from '@xyflow/react';
+ *
+ *const initialNodes = [];
+ *const initialEdges = [];
+ *
+ *export default function () {
+ *  const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes);
+ *  const [edges, setEdges, onEdgesChange] = useEdgesState(initialEdges);
+ *
+ *  return (
+ *    <ReactFlow
+ *      nodes={nodes}
+ *      edges={edges}
+ *      onNodesChange={onNodesChange}
+ *      onEdgesChange={onEdgesChange}
+ *    />
+ *  );
+ *}
+ *```
+ *
+ * @remarks This hook was created to make prototyping easier and our documentation
+ * examples clearer. Although it is OK to use this hook in production, in
+ * practice you may want to use a more sophisticated state management solution
+ * like Zustand {@link https://reactflow.dev/docs/guides/state-management/} instead.
+ *
  */
 export function useEdgesState<EdgeType extends Edge = Edge>(
   initialEdges: EdgeType[]

packages/react/src/hooks/useNodesInitialized.ts

@@ -1,6 +1,7 @@
+import { nodeHasDimensions } from '@xyflow/system';
+
 import { useStore } from './useStore';
 import type { ReactFlowState } from '../types';
-import { nodeHasDimensions } from '@xyflow/system';
 
 export type UseNodesInitializedOptions = {
   includeHiddenNodes?: boolean;
@@ -22,18 +23,44 @@ const selector = (options: UseNodesInitializedOptions) => (s: ReactFlowState) =>
   return true;
 };
 
-const defaultOptions = {
-  includeHiddenNodes: false,
-};
-
 /**
- * Hook which returns true when all nodes are initialized.
+ * This hook tells you whether all the nodes in a flow have been measured and given
+ *a width and height. When you add a node to the flow, this hook will return
+ *`false` and then `true` again once the node has been measured.
  *
  * @public
  * @param options.includeHiddenNodes - defaults to false
  * @returns boolean indicating whether all nodes are initialized
+ *
+ * @example
+ * ```jsx
+ *import { useReactFlow, useNodesInitialized } from '@xyflow/react';
+ *import { useEffect, useState } from 'react';
+ *
+ *const options = {
+ *  includeHiddenNodes: false,
+ *};
+ *
+ *export default function useLayout() {
+ *  const { getNodes } = useReactFlow();
+ *  const nodesInitialized = useNodesInitialized(options);
+ *  const [layoutedNodes, setLayoutedNodes] = useState(getNodes());
+ *
+ *  useEffect(() => {
+ *    if (nodesInitialized) {
+ *      setLayoutedNodes(yourLayoutingFunction(getNodes()));
+ *    }
+ *  }, [nodesInitialized]);
+ *
+ *  return layoutedNodes;
+ *}
+ *```
  */
-export function useNodesInitialized(options: UseNodesInitializedOptions = defaultOptions): boolean {
+export function useNodesInitialized(
+  options: UseNodesInitializedOptions = {
+    includeHiddenNodes: false,
+  }
+): boolean {
   const initialized = useStore(selector(options));
 
   return initialized;

packages/react/src/hooks/useOnSelectionChange.ts

@@ -8,10 +8,42 @@ export type UseOnSelectionChangeOptions = {
 };
 
 /**
- * Hook for registering an onSelectionChange handler.
+ * This hook lets you listen for changes to both node and edge selection. As the
+ *name implies, the callback you provide will be called whenever the selection of
+ *_either_ nodes or edges changes.
  *
  * @public
  * @param params.onChange - The handler to register
+ *
+ * @example
+ * ```jsx
+ *import { useState } from 'react';
+ *import { ReactFlow, useOnSelectionChange } from '@xyflow/react';
+ *
+ *function SelectionDisplay() {
+ *  const [selectedNodes, setSelectedNodes] = useState([]);
+ *  const [selectedEdges, setSelectedEdges] = useState([]);
+ *
+ *  // the passed handler has to be memoized, otherwise the hook will not work correctly
+ *  const onChange = useCallback(({ nodes, edges }) => {
+ *    setSelectedNodes(nodes.map((node) => node.id));
+ *    setSelectedEdges(edges.map((edge) => edge.id));
+ *  }, []);
+ *
+ *  useOnSelectionChange({
+ *    onChange,
+ *  });
+ *
+ *  return (
+ *    <div>
+ *      <p>Selected nodes: {selectedNodes.join(', ')}</p>
+ *      <p>Selected edges: {selectedEdges.join(', ')}</p>
+ *    </div>
+ *  );
+ *}
+ *```
+ *
+ * @remarks You need to memoize the passed `onChange` handler, otherwise the hook will not work correctly.
  */
 export function useOnSelectionChange({ onChange }: UseOnSelectionChangeOptions) {
   const store = useStoreApi();

packages/react/src/hooks/useOnViewportChange.ts

@@ -10,12 +10,30 @@ export type UseOnViewportChangeOptions = {
 };
 
 /**
- * Hook for registering an onViewportChange handler.
+ * The `useOnViewportChange` hook lets you listen for changes to the viewport such
+ *as panning and zooming. You can provide a callback for each phase of a viewport
+ *change: `onStart`, `onChange`, and `onEnd`.
  *
  * @public
  * @param params.onStart - gets called when the viewport starts changing
  * @param params.onChange - gets called when the viewport changes
  * @param params.onEnd - gets called when the viewport stops changing
+ *
+ * @example
+ * ```jsx
+ *import { useCallback } from 'react';
+ *import { useOnViewportChange } from '@xyflow/react';
+ *
+ *function ViewportChangeLogger() {
+ *  useOnViewportChange({
+ *    onStart: (viewport: Viewport) => console.log('start', viewport),
+ *    onChange: (viewport: Viewport) => console.log('change', viewport),
+ *    onEnd: (viewport: Viewport) => console.log('end', viewport),
+ *  });
+ *
+ *  return null;
+ *}
+ *```
  */
 export function useOnViewportChange({ onStart, onChange, onEnd }: UseOnViewportChangeOptions) {
   const store = useStoreApi();

packages/react/src/hooks/useReactFlow.ts

@@ -20,10 +20,33 @@ import type { ReactFlowInstance, Node, Edge, InternalNode, ReactFlowState, Gener
 const selector = (s: ReactFlowState) => !!s.panZoom;
 
 /**
- * Hook for accessing the ReactFlow instance.
+ * This hook returns a ReactFlowInstance that can be used to update nodes and edges, manipulate the viewport, or query the current state of the flow.
  *
  * @public
  * @returns ReactFlowInstance
+ *
+ * @example
+ * ```jsx
+ *import { useCallback, useState } from 'react';
+ *import { useReactFlow } from '@xyflow/react';
+ *
+ *export function NodeCounter() {
+ *  const reactFlow = useReactFlow();
+ *  const [count, setCount] = useState(0);
+ *  const countNodes = useCallback(() => {
+ *    setCount(reactFlow.getNodes().length);
+ *    // you need to pass it as a dependency if you are using it with useEffect or useCallback
+ *    // because at the first render, it's not initialized yet and some functions might not work.
+ *  }, [reactFlow]);
+ *
+ *  return (
+ *    <div>
+ *      <button onClick={countNodes}>Update count</button>
+ *      <p>There are {count} nodes in the flow.</p>
+ *    </div>
+ *  );
+ *}
+ *```
  */
 export function useReactFlow<NodeType extends Node = Node, EdgeType extends Edge = Edge>(): ReactFlowInstance<
   NodeType,

packages/react/src/hooks/useStore.ts

@@ -9,7 +9,9 @@ import type { Edge, Node, ReactFlowState } from '../types';
 const zustandErrorMessage = errorMessages['error001']();
 
 /**
- * Hook for accessing the internal store. Should only be used in rare cases.
+ * This hook can be used to subscribe to internal state changes of the React Flow
+ * component. The `useStore` hook is re-exported from the [Zustand](https://github.com/pmndrs/zustand)
+ * state management library, so you should check out their docs for more details.
  *
  * @public
  * @param selector
@@ -17,8 +19,13 @@ const zustandErrorMessage = errorMessages['error001']();
  * @returns The selected state slice
  *
  * @example
- * const nodes = useStore((state: ReactFlowState<MyNodeType>) => state.nodes);
+ * ```ts
+ * const nodes = useStore((state) => state.nodes);
+ * ```
  *
+ * @remarks This hook should only be used if there is no other way to access the internal
+ * state. For many of the common use cases, there are dedicated hooks available
+ * such as {@link useReactFlow}, {@link useViewport}, etc.
  */
 function useStore<StateSlice = unknown>(
   selector: (state: ReactFlowState) => StateSlice,
@@ -33,6 +40,20 @@ function useStore<StateSlice = unknown>(
   return useZustandStore(store, selector, equalityFn);
 }
 
+/**
+ * In some cases, you might need to access the store directly. This hook returns the store object which can be used on demand to access the state or dispatch actions.
+ *
+ * @returns The store object
+ *
+ * @example
+ * ```ts
+ * const store = useStoreApi();
+ * ```
+ *
+ * @remarks This hook should only be used if there is no other way to access the internal
+ * state. For many of the common use cases, there are dedicated hooks available
+ * such as {@link useReactFlow}, {@link useViewport}, etc.
+ */
 function useStoreApi<NodeType extends Node = Node, EdgeType extends Edge = Edge>() {
   const store = useContext(StoreContext) as UseBoundStoreWithEqualityFn<
     StoreApi<ReactFlowState<NodeType, EdgeType>>

packages/react/src/hooks/useUpdateNodeInternals.ts

@@ -4,10 +4,48 @@ import type { UpdateNodeInternals, InternalNodeUpdate } from '@xyflow/system';
 import { useStoreApi } from '../hooks/useStore';
 
 /**
- * Hook for updating node internals.
+ * When you programmatically add or remove handles to a node or update a node's
+ *handle position, you need to let React Flow know about it using this hook. This
+ *will update the internal dimensions of the node and properly reposition handles
+ *on the canvas if necessary.
  *
  * @public
  * @returns function for updating node internals
+ *
+ * @example
+ * ```jsx
+ *import { useCallback, useState } from 'react';
+ *import { Handle, useUpdateNodeInternals } from '@xyflow/react';
+ *
+ *export default function RandomHandleNode({ id }) {
+ *  const updateNodeInternals = useUpdateNodeInternals();
+ *  const [handleCount, setHandleCount] = useState(0);
+ *  const randomizeHandleCount = useCallback(() => {
+ *   setHandleCount(Math.floor(Math.random() * 10));
+ *    updateNodeInternals(id);
+ *  }, [id, updateNodeInternals]);
+ *
+ *  return (
+ *    <>
+ *      {Array.from({ length: handleCount }).map((_, index) => (
+ *        <Handle
+ *          key={index}
+ *          type="target"
+ *          position="left"
+ *          id={`handle-${index}`}
+ *        />
+ *      ))}
+ *
+ *      <div>
+ *        <button onClick={randomizeHandleCount}>Randomize handle count</button>
+ *        <p>There are {handleCount} handles on this node.</p>
+ *      </div>
+ *    </>
+ *  );
+ *}
+ *```
+ * @remarks This hook can only be used in a component that is a child of a
+ *{@link ReactFlowProvider} or a {@link ReactFlow} component.
  */
 export function useUpdateNodeInternals(): UpdateNodeInternals {
   const store = useStoreApi();

packages/react/src/hooks/useViewport.ts

@@ -11,10 +11,33 @@ const viewportSelector = (state: ReactFlowState) => ({
 });
 
 /**
- * Hook for getting the current viewport from the store.
+ * The `useViewport` hook is a convenient way to read the current state of the
+ *{@link Viewport} in a component. Components that use this hook
+ *will re-render **whenever the viewport changes**.
  *
  * @public
  * @returns The current viewport
+ *
+ * @example
+ *
+ *```jsx
+ *import { useViewport } from '@xyflow/react';
+ *
+ *export default function ViewportDisplay() {
+ *  const { x, y, zoom } = useViewport();
+ *
+ *  return (
+ *    <div>
+ *      <p>
+ *        The viewport is currently at ({x}, {y}) and zoomed to {zoom}.
+ *      </p>
+ *    </div>
+ *  );
+ *}
+ *```
+ *
+ * @remarks This hook can only be used in a component that is a child of a
+ *{@link ReactFlowProvider} or a {@link ReactFlow} component.
  */
 export function useViewport(): Viewport {
   const viewport = useStore(viewportSelector, shallow);

packages/react/src/hooks/useVisibleNodeIds.ts

@@ -8,8 +8,8 @@ import type { Node, ReactFlowState } from '../types';
 const selector = (onlyRenderVisible: boolean) => (s: ReactFlowState) => {
   return onlyRenderVisible
     ? getNodesInside<Node>(s.nodeLookup, { x: 0, y: 0, width: s.width, height: s.height }, s.transform, true).map(
-        (node) => node.id
-      )
+      (node) => node.id
+    )
     : Array.from(s.nodeLookup.keys());
 };