A powerful and flexible API for adding annotations to your application
If there is a useCordAnnotationRenderer
handler registered for the exact location of the annotation, we use the return value of that handler.
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.
If there is a useCordAnnotationRenderer
handler registered on a partial match of the annotation location, we use the return value of that handler.
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.
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 }
Type definition of an annotation.
type Annotation<L extends Location = {}> = {
id: string;
location: L;
};
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.
type AnnotationCapturePosition = {
element: HTMLElement;
x: number;
y: number;
};
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;
};
type AnnotationPositionRendererCallback<L extends Location = {}> = (
annotation: Annotation<L>,
coordsRelativeToTarget: { x: number; y: number },
) => AnnotationRenderPosition | null | undefined | void;
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;
};
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;
Clears any capture handler function previously defined on the location
.
// defined in window.CordSDK.annotation
function clearCaptureHandler(location: Location): void;
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;
Clears any render handler function previously defined on the location
.
// defined in window.CordSDK.annotation
function clearRenderHandler(location: Location): void;
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;
Clears any click handler function previously defined on the location
.
// defined in window.CordSDK.annotation
function clearClickHandler(location: Location): void;
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>;
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;
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;
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 };