Reference

How Cord decides where to place the annotation pin

1. If there is a useCordAnnotationRenderer handler registered on the exact same 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 same 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 annotation target element that the annotation was captured within
• x and y reflect 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: in this object you can provide additional data to be stored in the location of the annotation that was just captured
• label: provide this field to customize the label of the annotation when seen in a message.

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; if element is not specified, these coordinates will be assumed to be relative to the document; the coordinates can also be provided as percentages of the dimensions of element, for example "30%"
• element: the HTML element the coordinates should be relative to

type AnnotationRenderPosition = {
  coordinates?: {
    x: number | string;
    y: number | string;
  };
  element?: HTMLElement;
};

In this section