Link copied to clipboard!
Mobile navigation button - closed state

Annotations API

The details behind specifying annotation locations


How Cord decides where to place the annotation pin

  1. If there is a useCordAnnotationRenderer handler registered for the exact location of the annotation, we use the return value of that handler.

  2. If there is an element on the page decorated with a data-cord-annotation-location attribute with the exact location of the annotation, we place the pin at the x/y coordinates (scaled proportional to the dimensions of the element), where the user clicked when they placed the annotation.

  3. If there is a useCordAnnotationRenderer handler registered on a partial match of the annotation location, we use the return value of that handler.

  4. If there is an element on the page decorated with a data-cord-annotation-location attribute which partially matches the location of the annotation, we place the pin in the center of that element and show a tooltip indicating that the content may have changed.

useCordAnnotationTargetRef

Helper function that annotates an element with the data-cord-annotation-location attribute, the value being a stable serialisation of the location you provide. Returns a React ref object.

function useCordAnnotationTargetRef<
  E extends HTMLElement,
  L extends Location = {}
>(location: Partial<L>): React.MutableRefObject<E | null>;

useCordAnnotationCaptureHandler

Registers a handler function that will be called by Cord when the user places an annotation pin inside an annotation target element that matches the location.

function useCordAnnotationCaptureHandler<L extends Location = {}>(
  location: Partial<L>,
  handler: (
    capturePosition: AnnotationCapturePosition,
    element: HTMLElement
  ) => AnnotationCaptureResult | undefined | void;
): void;

useCordAnnotationClickHandler

Registers a handler function that will be called by Cord when the user clicks an annotation in the sidebar whose location matches the location argument.

function useCordAnnotationClickHandler<L extends Location = {}>(
  location: Partial<L>,
  handler: (annotation: Annotation<L>) => unknown
): void;

useCordAnnotationRenderer

Registers a handler function that will be called by Cord when an annotation needs to be rendered, allowing you to provide a specific position for the annotation pin, either absolute or relative to an element. Returns a redrawAnnotations function you can optionally use to re-calculate the annotations’ positions and re-draw them.

function useCordAnnotationRenderer<L extends Location = {}>(
  location: Partial<L>,
  handler: (
    annotation: Annotation<L>
  ) => AnnotationRenderPosition | null | undefined | void
): { redrawAnnotations: () => void };

Location

Type definition of a location: flat object where the values can be either string, number or boolean.

type Location = Record<string, string | number | boolean>;

Annotation

Type definition of an annotation.

type Annotation<L extends Location = {}> = {
  id: string;
  location: L;
};

AnnotationCapturePosition

Type definition for the first argument received by the handler you provide to useCordAnnotationCaptureHandler, indicates the position the user clicked relative to an annotation target element.

  • element is the DOM element that the annotation was captured within.
  • x and y are the pixel coordinates of the user click relative to the annotation target element.
type AnnotationCapturePosition = {
  element: HTMLElement;
  x: number;
  y: number;
};

AnnotationCaptureResult

Type definition for the return value of the handler you provide to useCordAnnotationCaptureHandler.

  • extraLocation: data to be added to the location of the annotation that was captured.
  • label: the user-visible label of the annotation.
type AnnotationCaptureResult<L extends Location = {}> = {
  extraLocation?: Partial<L>;
  label?: string;
};

AnnotationRenderPosition

Type definition for the return value of the handler you provide to useCordAnnotationRenderer. This object lets you customize where the annotation pointer should be rendered.

  • coordinates: lets you specify x and y coordinates for the annotation pointer, relative to element. The coordinates can also be provided as percentages of the dimensions of element, for example "30%". If element is not specified, the coordinates will be interpreted relative to the document.
  • element: the HTML element the coordinates should be relative to.
type AnnotationRenderPosition = {
  coordinates?: {
    x: number | string;
    y: number | string;
  };
  element?: HTMLElement;
};