toolmark-monorepo / @toolmark/react / useToolAnchor

Function: useToolAnchor()

useToolAnchor(tool, param?): AnchorRefCallback

Defined in: packages/react/src/use-tool-anchor.ts:88

Anchors a tool (or one of its params) to a custom widget for tours (spec §13): returns a ref callback to put on the element, e.g. <canvas ref={useToolAnchor('chart.zoom', 'level')} />.

On attach it calls tm.setAnchor(tool, param, el), which wins over the tool's own anchors; on detach or unmount it clears the override with tm.setAnchor(tool, param, null). The registry drops a tool's overrides when the tool is disposed, so the override is re-applied after every registry revision while the element stays attached (a StrictMode remount or a useTool dependency change re-registers the tool). Values that are not DOM elements are ignored.

The callback is stable for a given tool and param; changing either detaches the old anchor and attaches the new one.

One override exists per (tool, param): when two mounted components anchor the same pair, the last one to attach (or re-apply) wins, and the first to detach may clear it for both. Anchor each (tool, param) from one component only.

Parameters

tool

string

Full tool name, as in the manifest (scope path included).

param?

string

Input path the element stands for; omit for the tool's own element.

Returns

AnchorRefCallback

A ref callback.