Hooks Reference

Annotorious provides hooks for accessing the anno Annotator instance, annotations, and other API features. These hooks are available anywhere below the <Annotorious> context provider.

Tip

If these hooks are not working for you, double check that you wrapped your application (or the component that holds your annotatable image) with the <Annotorious> context tag. Forgetting the context wrapper is a small but common mistake.

useAnnotation

const annotation = useAnnotation(id);

Retrieves a single annotation by its ID and subscribes to changes.

Argument	Type	Description
id	string	The ID of the annotation to retrieve.

Returns: ImageAnnotation | undefined

useAnnotations

const annotations: ImageAnnotation[] = useAnnotations(debounce);

Returns the live annotation state. To limit re-rendering, you can optionally debounce the state updates.

Argument	Type	Default	Description
debounce	number	0	Debounce the state update by the given number of milliseconds.

Returns: Array<ImageAnnotation>

useAnnotator

const anno = useAnnotator();

Provides access to the vanilla ImageAnnotator or OpenSeadragonAnnotator instance. In TypeScript, you can include a type argument to indicate the return type.

const imageAnnotator = useAnnotator<AnnotoriousImageAnnotator>();

// or

const osdAnnotator = useAnnotator<AnnotoriousOpenSeadragonAnnotator>();

Note: in the React bindings package, the types for ImageAnnotator and OpenSeadragonAnnotator are renamed to AnnotoriousImageAnnotator and AnnotoriousOpenSeadragonAnnotator to prevent name clashes with the React components of the same name.

Returns: ImageAnnotator | OpenSeadragonAnnotator

useAnnotatorUser

Returns the current annotator user set via the anno.setUser() method, if any.

const user: User = useAnnotatorUser();

Returns: User

useSelection

const { selected, event } = useSelection();

Returns the current selection state object and, optionally, the associated pointer event.

Returns:

Argument	Type	Description
selected	Array<Selection>	The selected annotations.
event	PointerEvent	Optional. The associated user pointer event.

Selection

The selection object contains the selected annotation and a flag indicating whether the selected annotation has been made editable by the selection.

Argument	Type	Description
annotation	ImageAnnotation	The selected annotations.
editable	boolean	Optional. Whether the annotation is currently editable.

useViewportState

const annotations: ImageAnnotation[] = useViewportState(debounce);

OpenSeadragon only. Returns the annotations currently visible in the viewport. This hook is only available with OpenSeadragon, and will respond to zooming and panning of the OpenSeadragon image. You can optionally debounce this hook, to limit re-rendering.

Argument	Type	Default	Description
debounce	number	0	Debounce the state update by the given number of milliseconds.

Returns: Array<ImageAnnotation>