or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

annotations.mdchart-components.mdchart-container.mdg-components.mdg2-integration.mdgeometry-components.mdindex.mdmigration-guide.mdreact-hooks.mdstatistical-charts.mdtheme-system.mdutilities.md
tile.json

annotations.mddocs/

Annotations

Annotations provide a powerful way to add supplementary information to charts including text labels, lines, regions, images, and interactive markers. They help highlight important data points, trends, and provide contextual information.

Capabilities

Annotation Namespace

All annotation components are available under the Annotation namespace.

/**
 * Annotation namespace containing all annotation components
 */
declare namespace Annotation {
  const Arc: React.FC<IArcProps>;
  const DataMarker: React.FC<IDataMarkerProps>;
  const DataRegion: React.FC<IDataRegionProps>;
  const RegionFilter: React.FC<IRegionFilterProps>;
  const Html: React.FC<IHtmlProps>;
  const ReactElement: React.FC<IReactElementProps>;
  const Image: React.FC<IImageProps>;
  const Line: React.FC<ILineProps>;
  const Region: React.FC<IRegionProps>;
  const Text: React.FC<ITextProps>;
  const Base: React.FC<IBaseProps>;
}

Text Annotation

Adds text labels to specific positions on the chart.

/**
 * Text annotation for adding text labels to charts
 */
interface ITextProps {
  /** Text position coordinates */
  position?: [string | number, string | number] | ((xScale: any, yScale: any) => [number, number]);
  /** Text content */
  content?: string;
  /** Text style */
  style?: {
    fill?: string;
    fontSize?: number;
    fontWeight?: string | number;
    textAlign?: 'start' | 'middle' | 'end';
    textBaseline?: 'top' | 'middle' | 'bottom';
    fontFamily?: string;
    opacity?: number;
    [key: string]: any;
  };
  /** Text rotation angle */
  rotate?: number;
  /** Text offset from position */
  offsetX?: number;
  /** Text offset from position */
  offsetY?: number;
  /** Animation configuration */
  animate?: boolean | object;
  /** Whether annotation is rendered on top */
  top?: boolean;
}

declare const Text: React.FC<ITextProps>;

Usage Examples:

import React from "react";
import { Chart, Line, Annotation } from "bizcharts";

// Basic text annotation
function TextAnnotationChart() {
  return (
    <Chart height={400} data={data} autoFit>
      <Line position="month*value" />
      <Annotation.Text
        position={['2020-03', 50]}
        content="Peak Value"
        style={{
          fill: '#ff4d4f',
          fontSize: 14,
          fontWeight: 'bold',
          textAlign: 'middle'
        }}
        offsetY={-20}
      />
    </Chart>
  );
}

// Multiple text annotations
function MultipleTextChart() {
  return (
    <Chart height={400} data={data} autoFit>
      <Line position="x*y" />
      <Annotation.Text
        position={['min', 'median']}
        content="Start Point"
        style={{ fill: '#1890ff' }}
      />
      <Annotation.Text
        position={['max', 'median']}
        content="End Point"
        style={{ fill: '#52c41a' }}
      />
    </Chart>
  );
}

Line Annotation

Adds reference lines to highlight trends or thresholds.

/**
 * Line annotation for adding reference lines
 */
interface ILineProps {
  /** Line start position */
  start?: [string | number, string | number];
  /** Line end position */
  end?: [string | number, string | number];
  /** Line style */
  style?: {
    stroke?: string;
    lineWidth?: number;
    lineDash?: number[];
    opacity?: number;
    [key: string]: any;
  };
  /** Line text label */
  text?: {
    content?: string;
    position?: 'start' | 'center' | 'end' | '0%' | '50%' | '100%';
    style?: object;
    offsetX?: number;
    offsetY?: number;
    autoRotate?: boolean;
  };
  /** Animation configuration */
  animate?: boolean | object;
  /** Whether annotation is rendered on top */
  top?: boolean;
}

declare const Line: React.FC<ILineProps>;

Usage Examples:

// Reference line with threshold
function ReferenceLineChart() {
  return (
    <Chart height={400} data={data} autoFit>
      <Line position="month*value" />
      <Annotation.Line
        start={['min', 40]}
        end={['max', 40]}
        style={{
          stroke: '#ff4d4f',
          lineWidth: 2,
          lineDash: [4, 4]
        }}
        text={{
          content: 'Target Line',
          position: 'end',
          style: { fill: '#ff4d4f', fontSize: 12 },
          offsetY: -10
        }}
      />
    </Chart>
  );
}

// Vertical line marker
function VerticalLineChart() {
  return (
    <Chart height={400} data={data} autoFit>
      <Line position="date*value" />
      <Annotation.Line
        start={['2020-03-15', 'min']}
        end={['2020-03-15', 'max']}
        style={{
          stroke: '#722ed1',
          lineWidth: 1
        }}
        text={{
          content: 'Important Date',
          position: 'start',
          style: { fill: '#722ed1' }
        }}
      />
    </Chart>
  );
}

Region Annotation

Highlights specific areas or ranges in the chart.

/**
 * Region annotation for highlighting chart areas
 */
interface IRegionProps {
  /** Region start position */
  start?: [string | number, string | number];
  /** Region end position */
  end?: [string | number, string | number];
  /** Region style */
  style?: {
    fill?: string;
    fillOpacity?: number;
    stroke?: string;
    lineWidth?: number;
    opacity?: number;
    [key: string]: any;
  };
  /** Animation configuration */
  animate?: boolean | object;
  /** Whether annotation is rendered on top */
  top?: boolean;
}

declare const Region: React.FC<IRegionProps>;

Usage Examples:

// Highlighted time period
function RegionAnnotationChart() {
  return (
    <Chart height={400} data={data} autoFit>
      <Line position="date*value" />
      <Annotation.Region
        start={['2020-02-01', 'min']}
        end={['2020-04-01', 'max']}
        style={{
          fill: '#ffc53d',
          fillOpacity: 0.2
        }}
      />
    </Chart>
  );
}

// Value range highlight
function ValueRangeChart() {
  return (
    <Chart height={400} data={data} autoFit>
      <Line position="x*y" />
      <Annotation.Region
        start={['min', 30]}
        end={['max', 50]}
        style={{
          fill: '#52c41a',
          fillOpacity: 0.15
        }}
      />
    </Chart>
  );
}

Data Marker Annotation

Creates markers that point to specific data points.

/**
 * Data marker annotation for highlighting specific data points
 */
interface IDataMarkerProps {
  /** Data point position */
  position?: [string | number, string | number];
  /** Marker point configuration */
  point?: {
    style?: object;
    size?: number;
  };
  /** Marker line configuration */
  line?: {
    style?: object;
    length?: number;
  };
  /** Marker text configuration */
  text?: {
    content?: string;
    style?: object;
    offsetX?: number;
    offsetY?: number;
  };
  /** Auto-adjust position to avoid overlap */
  autoAdjust?: boolean;
  /** Marker direction */
  direction?: 'upward' | 'downward';
  /** Animation configuration */
  animate?: boolean | object;
  /** Whether annotation is rendered on top */
  top?: boolean;
}

declare const DataMarker: React.FC<IDataMarkerProps>;

Usage Examples:

// Data point marker
function DataMarkerChart() {
  return (
    <Chart height={400} data={data} autoFit>
      <Line position="month*value" />
      <Annotation.DataMarker
        position={['2020-05', 78]}
        text={{
          content: 'Highest Point\n78.5',
          style: {
            textAlign: 'center',
            fontSize: 12
          }
        }}
        line={{
          length: 30,
          style: { stroke: '#ff4d4f' }
        }}
        point={{
          style: { fill: '#ff4d4f', r: 4 }
        }}
        direction="downward"
      />
    </Chart>
  );
}

Data Region Annotation

Highlights data ranges with contextual information.

/**
 * Data region annotation for highlighting data ranges
 */
interface IDataRegionProps {
  /** Region start position */
  start?: [string | number, string | number];
  /** Region end position */
  end?: [string | number, string | number];
  /** Region style */
  style?: object;
  /** Region label text */
  text?: {
    content?: string;
    style?: object;
    position?: string;
  };
  /** Animation configuration */
  animate?: boolean | object;
  /** Whether annotation is rendered on top */
  top?: boolean;
}

declare const DataRegion: React.FC<IDataRegionProps>;

Image Annotation

Adds images to charts for branding or visual enhancement.

/**
 * Image annotation for adding images to charts
 */
interface IImageProps {
  /** Image position */
  position?: [string | number, string | number];
  /** Image source URL */
  src?: string;
  /** Image width */
  width?: number;
  /** Image height */
  height?: number;
  /** Image offset X */
  offsetX?: number;
  /** Image offset Y */
  offsetY?: number;
  /** Animation configuration */
  animate?: boolean | object;
  /** Whether annotation is rendered on top */
  top?: boolean;
}

declare const Image: React.FC<IImageProps>;

HTML Annotation

Embeds custom HTML content within charts.

/**
 * HTML annotation for embedding custom HTML content
 */
interface IHtmlProps {
  /** HTML position */
  position?: [string | number, string | number];
  /** HTML content */
  html?: string;
  /** HTML offset X */
  offsetX?: number;
  /** HTML offset Y */
  offsetY?: number;
  /** Z-index for layering */
  zIndex?: number;
  /** Whether annotation is rendered on top */
  top?: boolean;
}

declare const Html: React.FC<IHtmlProps>;

React Element Annotation

Embeds React components as annotations.

/**
 * React element annotation for embedding React components
 */
interface IReactElementProps {
  /** Element position */
  position?: [string | number, string | number];
  /** React element to render */
  children?: React.ReactNode;
  /** Element offset X */
  offsetX?: number;
  /** Element offset Y */
  offsetY?: number;
  /** Whether annotation is rendered on top */
  top?: boolean;
}

declare const ReactElement: React.FC<IReactElementProps>;

Arc Annotation

Creates arc shapes for highlighting curved areas.

/**
 * Arc annotation for creating arc shapes
 */
interface IArcProps {
  /** Arc start position */
  start?: [string | number, string | number];
  /** Arc end position */
  end?: [string | number, string | number];
  /** Arc style */
  style?: object;
  /** Animation configuration */
  animate?: boolean | object;
  /** Whether annotation is rendered on top */
  top?: boolean;
}

declare const Arc: React.FC<IArcProps>;

Region Filter Annotation

Creates interactive filter regions that affect data visibility.

/**
 * Region filter annotation for interactive data filtering
 */
interface IRegionFilterProps {
  /** Filter start position */
  start?: [string | number, string | number];
  /** Filter end position */
  end?: [string | number, string | number];
  /** Filter color */
  color?: string;
  /** Animation configuration */
  animate?: boolean | object;
  /** Whether annotation is rendered on top */
  top?: boolean;
}

declare const RegionFilter: React.FC<IRegionFilterProps>;

Usage Examples:

// Combined annotations
function ComplexAnnotationChart() {
  return (
    <Chart height={400} data={data} autoFit>
      <Line position="month*value" />
      
      {/* Background region */}
      <Annotation.Region
        start={['2020-02', 'min']}
        end={['2020-04', 'max']}
        style={{ fill: '#f0f0f0', fillOpacity: 0.5 }}
      />
      
      {/* Reference line */}
      <Annotation.Line
        start={['min', 50]}
        end={['max', 50]}
        style={{ stroke: '#ff4d4f', lineDash: [4, 4] }}
      />
      
      {/* Peak marker */}
      <Annotation.DataMarker
        position={['2020-05', 85]}
        text={{ content: 'Peak\n85' }}
        direction="downward"
      />
      
      {/* Additional text */}
      <Annotation.Text
        position={['2020-01', 20]}
        content="Low Season"
        style={{ fill: '#666', fontSize: 12 }}
      />
    </Chart>
  );
}

Types

// Common position type  
type AnnotationPosition = [string | number, string | number] | ((xScale: any, yScale: any) => [number, number]);

// Style configuration
interface AnnotationStyle {
  fill?: string;
  stroke?: string;
  lineWidth?: number;
  lineDash?: number[];
  opacity?: number;
  fontSize?: number;
  fontFamily?: string;
  fontWeight?: string | number;
  textAlign?: 'start' | 'middle' | 'end';
  textBaseline?: 'top' | 'middle' | 'bottom';
  [key: string]: any;
}

// Animation configuration
type AnimationConfig = boolean | {
  duration?: number;
  easing?: string;
  delay?: number;
};

// Text configuration
interface TextConfig {
  content?: string;
  position?: string;
  style?: AnnotationStyle;
  offsetX?: number;
  offsetY?: number;
  autoRotate?: boolean;
}

// Base annotation properties
interface IBaseProps {
  animate?: AnimationConfig;
  top?: boolean;
  [key: string]: any;
}