Annotations API

A powerful and flexible API for adding annotations to your application


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.


API Objects

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>;
  
// Example:
// { route: '/dashboard/2', graph: '30d Revenue', x: 379, y: 231 }
Copy

Annotation

Type definition of an annotation.

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

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

AnnotationCaptureResult

Type definition for the return value of the handler you provide touseCordAnnotationCaptureHandler.

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

AnnotationPositionRendererCallback

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

AnnotationRenderPosition

Type definition for the return value of the handler you provide touseCordAnnotationRenderer. 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;
};
Copy

API Functions

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.annotation
function setCaptureHandler<L extends Location>(
  location: L,
  handler: (
    capturePosition: AnnotationCapturePosition,
    element: HTMLElement,
  ) => AnnotationCaptureResult | undefined | void,
): void;
Copy

clearCaptureHandler

Clears any capture handler function previously defined on the location.

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

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.annotation
function setRenderHandler<L extends Location>(
  location: L,
  handler: AnnotationPositionRendererCallback<L>,
): void;
Copy

clearRenderHandler

Clears any render handler function previously defined on the location.

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

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.annotation
function setClickHandler<L extends Location>(
  location: L,
  handler: (annotation: Annotation<L>) => unknown,
): void;
Copy

clearClickHandler

Clears any click handler function previously defined on the location.

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

useCordAnnotationTargetRef

Helper function that annotates an element with thedata-cord-annotation-location attribute, the value being a stable serialization 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>;
Copy

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

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: AnnotationWithThreadID<L>) => unknown
): void;
Copy

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