Cord LogoDocs
Sign inStart now

Annotations API

JavaScript APIs & Hooks /

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.

TypeScript:
type Location = Record<string, string | number | boolean>;
  
// Example:
// { route: '/dashboard/2', graph: '30d Revenue', x: 379, y: 231 }
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.

TypeScript:
type Annotation<L extends Location = {}> = {
  id: string;
  location: L;
};
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.
TypeScript:
type AnnotationCapturePosition = {
  element: HTMLElement;
  x: number;
  y: number;
};
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.
TypeScript:
type AnnotationCaptureResult<L extends Location = {}> = {
  extraLocation?: Partial<L>;
  label?: string;
};
type AnnotationCaptureResult<L extends Location = {}> = {
  extraLocation?: Partial<L>;
  label?: string;
};
Copy

AnnotationPositionRendererCallback #

TypeScript:
type AnnotationPositionRendererCallback<L extends Location = {}> = (
  annotation: Annotation<L>,
  coordsRelativeToTarget: { x: number; y: number },
) => AnnotationRenderPosition | null | undefined | void;
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.
TypeScript:
type AnnotationRenderPosition = {
  coordinates?: {
    x: number | string;
    y: number | string;
  };
  element?: HTMLElement;
};
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.

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

TypeScript:
// defined in window.CordSDK.annotation
function clearCaptureHandler(location: Location): void;
// 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.

TypeScript:
// defined in window.CordSDK.annotation
function setRenderHandler<L extends Location>(
  location: L,
  handler: AnnotationPositionRendererCallback<L>,
): void;
// 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.

TypeScript:
// defined in window.CordSDK.annotation
function clearRenderHandler(location: Location): void;
// 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.

TypeScript:
// defined in window.CordSDK.annotation
function setClickHandler<L extends Location>(
  location: L,
  handler: (annotation: Annotation<L>) => unknown,
): void;
// 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.

TypeScript:
// defined in window.CordSDK.annotation
function clearClickHandler(location: Location): void;
// 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.

TypeScript:
// exported by @cord-sdk/react
function useCordAnnotationTargetRef<
  E extends HTMLElement,
  L extends Location = {}
>(location: Partial<L>): React.MutableRefObject<E | null>;
// 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.

TypeScript:
// exported by @cord-sdk/react
function useCordAnnotationCaptureHandler<L extends Location = {}>(
  location: Partial<L>,
  handler: (
    capturePosition: AnnotationCapturePosition,
    element: HTMLElement,
  ) => AnnotationCaptureResult | undefined | void,
): void;
// 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.

TypeScript:
// exported by @cord-sdk/react
function useCordAnnotationClickHandler<L extends Location = {}>(
  location: Partial<L>,
  handler: (annotation: AnnotationWithThreadID<L>) => unknown
): void;
// 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.

TypeScript:
// exported by @cord-sdk/react
function useCordAnnotationRenderer<L extends Location = {}>(
  location: Partial<L>,
  handler: AnnotationPositionRendererCallback<L>,
): { redrawAnnotations: () => void };
// exported by @cord-sdk/react
function useCordAnnotationRenderer<L extends Location = {}>(
  location: Partial<L>,
  handler: AnnotationPositionRendererCallback<L>,
): { redrawAnnotations: () => void };
Copy

viewportCoordinatesToString #

Takes viewport coordinates and serializes them into a string which can later be turned back into viewport coordinates. This process encodes information about DOM structure and other information beyond just the coordinates so that they can be deserialized even by different users with different window sizes and even if the DOM has changed.
This function is used by Cord whenever an annotation is created in order to save the position of that annotation to the Cord backend.
Arguments
coords
required
Point2D
The current coordinates relative to the browser's viewport.

This is an object with the following fields:

x
required
number
y
required
number
Returns
An opaque serialized string, which can only be passed to stringToViewportCoordinates.

stringToViewportCoordinates #

Takes a serialized string from viewportCoordinatesToString and converts it back into viewport coordinates. The new coordinates are adjusted for changes in window size, DOM structure, etc. This means that even if the string was generated by a user on a different computer with a different window size, the resulting coordinates should point to an element that "feels like" "the same" element, even if its coordinates are quite different from when the string was originally generated.
This process can fail, for example if the DOM has changed too much or the original element simply does not exist in the DOM any more, and will return null in such cases.
This function is used by Cord whenever an annotation is rendered in order to position the annotation on the screen.
Arguments
str
required
string
A serialized string generated by viewportCoordinatesToString.
Returns
Viewport coordinates or null, as above.

Ask Cordy