Annotations API

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.

setCaptureHandler

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.

// defined in window.CordSDK.annotations
function setCaptureHandler<L extends Location>(
  location: L,
  handler: (
    capturePosition: AnnotationCapturePosition,
    element: HTMLElement,
  ) => AnnotationCaptureResult | undefined | void,
): void;

clearCaptureHandler

Clears any capture handler function previously defined on the location.

// defined in window.CordSDK.annotations
function clearCaptureHandler(location: Location): void;

setRenderHandler

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.

// defined in window.CordSDK.annotations
function setRenderHandler<L extends Location>(
  location: L,
  handler: AnnotationPositionRendererCallback<L>,
): void;

clearRenderHandler

Clears any render handler function previously defined on the location.

// defined in window.CordSDK.annotations
function clearRenderHandler(location: Location): void;

setClickHandler

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.

// defined in window.CordSDK.annotations
function setClickHandler<L extends Location>(
  location: L,
  handler: (annotation: Annotation<L>) => unknown,
): void;

clearClickHandler

Clears any click handler function previously defined on the location.

// defined in window.CordSDK.annotations
function clearClickHandler(location: Location): void;

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.

// exported by @cord-sdk/react
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.

// exported by @cord-sdk/react
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.

// exported by @cord-sdk/react
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.

// exported by @cord-sdk/react
function useCordAnnotationRenderer<L extends Location = {}>(
  location: Partial<L>,
  handler: AnnotationPositionRendererCallback<L>,
): { 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;
};

AnnotationPositionRendererCallback

type AnnotationPositionRendererCallback<L extends Location = {}> = (
  annotation: Annotation<L>,
  coordsRelativeToTarget: { x: number; y: number },
) => AnnotationRenderPosition | null | undefined | void;

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;
};