CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-plotly-js-dist

JavaScript data visualization library for creating interactive charts, graphs, and scientific visualizations

81

1.02x
Overview
Eval results
Files

chart-types.mddocs/

Chart Types

Plotly.js supports 48+ different chart types covering statistical, scientific, financial, geographic, and 3D visualizations. Each trace type has unique attributes and capabilities.

Basic Chart Types

Scatter Plots

The most versatile trace type supporting scatter plots, line charts, text charts, and bubble charts through mode variations.

interface ScatterTrace {
  type: 'scatter';
  x?: number[] | string[] | Date[];
  y?: number[];
  mode?: 'markers' | 'lines' | 'text' | 'lines+markers' | 'lines+text' | 'markers+text' | 'lines+markers+text' | 'none';
  text?: string | string[];
  textposition?: 'top left' | 'top center' | 'top right' | 'middle left' | 'middle center' | 'middle right' | 'bottom left' | 'bottom center' | 'bottom right';
  line?: {
    color?: string;
    width?: number;
    dash?: 'solid' | 'dot' | 'dash' | 'longdash' | 'dashdot' | 'longdashdot';
    shape?: 'linear' | 'spline' | 'hv' | 'vh' | 'hvh' | 'vhv';
    smoothing?: number;
  };
  marker?: {
    color?: string | string[] | number[];
    size?: number | number[];
    symbol?: string | string[];
    opacity?: number | number[];
    line?: {
      color?: string | string[];
      width?: number | number[];
    };
  };
  fill?: 'none' | 'tozeroy' | 'tozerox' | 'tonexty' | 'tonextx' | 'toself' | 'tonext';
  fillcolor?: string;
}

Usage Examples:

// Basic scatter plot
const scatter = {
  x: [1, 2, 3, 4, 5],
  y: [2, 4, 3, 5, 6],
  type: 'scatter',
  mode: 'markers',
  name: 'Data Points'
};

// Line chart
const line = {
  x: [1, 2, 3, 4, 5],
  y: [2, 4, 3, 5, 6],
  type: 'scatter',
  mode: 'lines',
  name: 'Trend Line'
};

// Bubble chart
const bubble = {
  x: [1, 2, 3, 4],
  y: [10, 11, 12, 13],
  type: 'scatter',
  mode: 'markers',
  marker: {
    size: [40, 60, 80, 100],
    color: ['red', 'blue', 'green', 'purple']
  },
  name: 'Bubble Chart'
};

// Area chart
const area = {
  x: [1, 2, 3, 4, 5],
  y: [2, 4, 3, 5, 6],
  type: 'scatter',
  mode: 'lines',
  fill: 'tozeroy',
  fillcolor: 'rgba(0,100,80,0.2)',
  name: 'Area Chart'
};

Bar Charts

Horizontal and vertical bar charts with extensive customization options.

interface BarTrace {
  type: 'bar';
  x?: string[] | number[];
  y?: number[];
  orientation?: 'v' | 'h';
  name?: string;
  text?: string | string[];
  textposition?: 'inside' | 'outside' | 'auto' | 'none';
  textangle?: number;
  insidetextanchor?: 'end' | 'middle' | 'start';
  marker?: {
    color?: string | string[] | number[];
    opacity?: number | number[];
    line?: {
      color?: string | string[];
      width?: number | number[];
    };
  };
  width?: number | number[];
  offset?: number | number[];
  base?: number | number[];
}

Usage Examples:

// Vertical bar chart
const verticalBar = {
  x: ['A', 'B', 'C', 'D'],
  y: [20, 14, 25, 16],
  type: 'bar',
  name: 'Vertical Bars'
};

// Horizontal bar chart
const horizontalBar = {
  x: [20, 14, 25, 16],
  y: ['A', 'B', 'C', 'D'],
  type: 'bar',
  orientation: 'h',
  name: 'Horizontal Bars'
};

// Grouped bar chart
const group1 = {
  x: ['Q1', 'Q2', 'Q3', 'Q4'],
  y: [20, 14, 25, 16],
  type: 'bar',
  name: 'Series 1'
};

const group2 = {
  x: ['Q1', 'Q2', 'Q3', 'Q4'],
  y: [16, 18, 22, 19],
  type: 'bar',
  name: 'Series 2'
};

// Stacked bar chart (set barmode: 'stack' in layout)

Pie Charts

Circular charts for showing proportional data with donut chart capability.

interface PieTrace {
  type: 'pie';
  labels?: string[];
  values?: number[];
  hole?: number; // 0-1, creates donut chart
  sort?: boolean;
  direction?: 'clockwise' | 'counterclockwise';
  rotation?: number;
  pull?: number | number[]; // 0-1, explodes sectors
  textinfo?: 'label' | 'text' | 'value' | 'percent' | 'label+text' | 'label+value' | 'label+percent' | 'text+value' | 'text+percent' | 'value+percent' | 'label+text+value' | 'label+text+percent' | 'label+value+percent' | 'text+value+percent' | 'label+text+value+percent' | 'none';
  textposition?: 'inside' | 'outside' | 'auto' | 'none';
  marker?: {
    colors?: string[];
    line?: {
      color?: string | string[];
      width?: number | number[];
    };
  };
}

Usage Examples:

// Basic pie chart
const pie = {
  labels: ['Oxygen', 'Hydrogen', 'Carbon', 'Nitrogen'],
  values: [4500, 2500, 1053, 500],
  type: 'pie',
  name: 'Elements'
};

// Donut chart
const donut = {
  labels: ['A', 'B', 'C'],
  values: [10, 20, 30],
  type: 'pie',
  hole: 0.4,
  name: 'Donut Chart'
};

// Exploded pie chart
const exploded = {
  labels: ['A', 'B', 'C', 'D'],
  values: [10, 15, 20, 25],
  type: 'pie',
  pull: [0, 0.1, 0, 0], // Explode second slice
  name: 'Exploded Pie'
};

Statistical Charts

Box Plots

Statistical distribution visualization showing quartiles, outliers, and whiskers.

interface BoxTrace {
  type: 'box';
  x?: string[] | number[];
  y?: number[];
  orientation?: 'v' | 'h';
  boxpoints?: 'all' | 'outliers' | 'suspectedoutliers' | false;
  boxmean?: boolean | 'sd';
  whiskerwidth?: number;
  marker?: {
    color?: string;
    size?: number;
    symbol?: string;
    opacity?: number;
  };
  line?: {
    color?: string;
    width?: number;
  };
  fillcolor?: string;
}

Violin Plots

Density distribution visualization combining box plot information with kernel density estimation.

interface ViolinTrace {
  type: 'violin';
  x?: string[] | number[];
  y?: number[];
  orientation?: 'v' | 'h';
  side?: 'both' | 'positive' | 'negative';
  width?: number;
  points?: 'all' | 'outliers' | 'suspectedoutliers' | false;
  box?: {
    visible?: boolean;
    width?: number;
    fillcolor?: string;
    line?: {
      color?: string;
      width?: number;
    };
  };
  meanline?: {
    visible?: boolean;
    color?: string;
    width?: number;
  };
}

Histograms

Distribution visualization for continuous data.

interface HistogramTrace {
  type: 'histogram';
  x?: number[];
  y?: number[];
  orientation?: 'v' | 'h';
  histnorm?: '' | 'percent' | 'probability' | 'density' | 'probability density';
  histfunc?: 'count' | 'sum' | 'avg' | 'min' | 'max';
  cumulative?: {
    enabled?: boolean;
    direction?: 'increasing' | 'decreasing';
    currentbin?: 'include' | 'exclude' | 'half';
  };
  nbinsx?: number;
  nbinsy?: number;
  autobinx?: boolean;
  autobiny?: boolean;
}

Scientific Charts

Heatmaps

2D data visualization using color intensity to represent values.

interface HeatmapTrace {
  type: 'heatmap';
  z: number[][];
  x?: string[] | number[];
  y?: string[] | number[];
  colorscale?: string | Array<[number, string]>;
  showscale?: boolean;
  zmin?: number;
  zmax?: number;
  zauto?: boolean;
  colorbar?: ColorbarConfig;
  xgap?: number;
  ygap?: number;
  zsmooth?: 'fast' | 'best' | false;
}

Contour Plots

Contour lines showing areas of equal value in 2D data.

interface ContourTrace {
  type: 'contour';
  z: number[][];
  x?: number[];
  y?: number[];
  colorscale?: string | Array<[number, string]>;
  showscale?: boolean;
  contours?: {
    start?: number;
    end?: number;
    size?: number;
    coloring?: 'fill' | 'heatmap' | 'lines' | 'none';
    showlines?: boolean;
    showlabels?: boolean;
  };
  line?: {
    color?: string;
    width?: number;
    dash?: string;
    smoothing?: number;
  };
}

3D Charts

3D Scatter Plots

Three-dimensional scatter plots with WebGL acceleration.

interface Scatter3DTrace {
  type: 'scatter3d';
  x?: number[];
  y?: number[];
  z?: number[];
  mode?: 'markers' | 'lines' | 'text' | 'lines+markers' | 'lines+text' | 'markers+text' | 'lines+markers+text';
  marker?: {
    size?: number | number[];
    color?: string | string[] | number[];
    colorscale?: string | Array<[number, string]>;
    opacity?: number; // Must be scalar for WebGL
    symbol?: string;
    line?: {
      color?: string;
      width?: number;
    };
  };
  line?: {
    color?: string;
    width?: number;
  };
  text?: string | string[];
  projection?: {
    x?: { show?: boolean; opacity?: number; scale?: number; };
    y?: { show?: boolean; opacity?: number; scale?: number; };
    z?: { show?: boolean; opacity?: number; scale?: number; };
  };
}

Surface Plots

3D surface visualization for mathematical functions or measured data.

interface SurfaceTrace {
  type: 'surface';
  z: number[][];
  x?: number[];
  y?: number[];
  colorscale?: string | Array<[number, string]>;
  showscale?: boolean;
  opacity?: number;
  surfacecolor?: number[][];
  contours?: {
    x?: { show?: boolean; start?: number; end?: number; size?: number; color?: string; };
    y?: { show?: boolean; start?: number; end?: number; size?: number; color?: string; };
    z?: { show?: boolean; start?: number; end?: number; size?: number; color?: string; };
  };
  lighting?: {
    ambient?: number;
    diffuse?: number;
    specular?: number;
    roughness?: number;
    fresnel?: number;
  };
}

Financial Charts

Candlestick Charts

OHLC financial data visualization with candlestick representation.

interface CandlestickTrace {
  type: 'candlestick';
  x?: Date[] | string[];
  open?: number[];
  high?: number[];
  low?: number[];
  close?: number[];
  increasing?: {
    line?: { color?: string; width?: number; };
    fillcolor?: string;
  };
  decreasing?: {
    line?: { color?: string; width?: number; };
    fillcolor?: string;
  };
  line?: {
    width?: number;
  };
  whiskerwidth?: number;
}

OHLC Charts

Open-High-Low-Close financial charts with traditional bar representation.

interface OHLCTrace {
  type: 'ohlc';
  x?: Date[] | string[];
  open?: number[];
  high?: number[];
  low?: number[];
  close?: number[];
  increasing?: {
    line?: { color?: string; width?: number; };
  };
  decreasing?: {
    line?: { color?: string; width?: number; };
  };
  line?: {
    width?: number;
  };
  tickwidth?: number;
}

Waterfall Charts

Cumulative effect visualization showing how initial value is affected by intermediate positive/negative changes.

interface WaterfallTrace {
  type: 'waterfall';
  x?: string[];
  y?: number[];
  base?: number;
  measure?: ('relative' | 'absolute' | 'total')[];
  text?: string | string[];
  textposition?: 'inside' | 'outside' | 'auto' | 'none';
  orientation?: 'v' | 'h';
  increasing?: {
    marker?: { color?: string; line?: { color?: string; width?: number; }; };
  };
  decreasing?: {
    marker?: { color?: string; line?: { color?: string; width?: number; }; };
  };
  totals?: {
    marker?: { color?: string; line?: { color?: string; width?: number; }; };
  };
}

Geographic Charts

Choropleth Maps

Geographic regions colored according to data values.

interface ChoroplethTrace {
  type: 'choropleth';
  locations?: string[];
  z?: number[];
  locationmode?: 'ISO-3' | 'USA-states' | 'country names' | 'geojson-id';
  geojson?: object;
  featureidkey?: string;
  colorscale?: string | Array<[number, string]>;
  showscale?: boolean;
  colorbar?: ColorbarConfig;
  marker?: {
    line?: {
      color?: string;
      width?: number;
    };
  };
}

Scatter Geo

Scatter plots on geographic maps.

interface ScatterGeoTrace {
  type: 'scattergeo';
  lon?: number[];
  lat?: number[];
  locations?: string[];
  locationmode?: 'ISO-3' | 'USA-states' | 'country names';
  mode?: 'markers' | 'lines' | 'text' | 'lines+markers' | 'lines+text' | 'markers+text' | 'lines+markers+text';
  marker?: {
    size?: number | number[];
    color?: string | string[] | number[];
    symbol?: string;
    opacity?: number | number[];
    line?: {
      color?: string | string[];
      width?: number | number[];
    };
  };
  line?: {
    color?: string;
    width?: number;
    dash?: string;
  };
  text?: string | string[];
}

Specialized Charts

Sankey Diagrams

Flow diagrams showing directed flows between nodes.

interface SankeyTrace {
  type: 'sankey';
  node?: {
    label?: string[];
    color?: string | string[];
    line?: {
      color?: string | string[];
      width?: number | number[];
    };
    pad?: number;
    thickness?: number;
    x?: number[];
    y?: number[];
  };
  link?: {
    source?: number[];
    target?: number[];
    value?: number[];
    color?: string | string[];
    line?: {
      color?: string | string[];
      width?: number | number[];
    };
  };
  orientation?: 'v' | 'h';
  arrangement?: 'snap' | 'perpendicular' | 'freeform' | 'fixed';
}

Treemap Charts

Hierarchical data visualization using nested rectangles.

interface TreemapTrace {
  type: 'treemap';
  labels?: string[];
  parents?: string[];
  values?: number[];
  ids?: string[];
  text?: string | string[];
  textinfo?: 'label' | 'text' | 'value' | 'label+text' | 'label+value' | 'text+value' | 'label+text+value' | 'none';
  branchvalues?: 'total' | 'remainder';
  level?: string;
  maxdepth?: number;
  marker?: {
    colors?: string[];
    colorscale?: string | Array<[number, string]>;
    showscale?: boolean;
    line?: {
      color?: string | string[];
      width?: number | number[];
    };
  };
  pathbar?: {
    visible?: boolean;
    side?: 'top' | 'bottom';
    edgeshape?: string;
    thickness?: number;
    textfont?: FontConfig;
  };
}

Sunburst Charts

Hierarchical data visualization using concentric circles.

interface SunburstTrace {
  type: 'sunburst';
  labels?: string[];
  parents?: string[];
  values?: number[];
  ids?: string[];
  text?: string | string[];
  textinfo?: 'label' | 'text' | 'value' | 'label+text' | 'label+value' | 'text+value' | 'label+text+value' | 'none';
  branchvalues?: 'total' | 'remainder';
  level?: string;
  maxdepth?: number;
  rotation?: number;
  sort?: boolean;
  marker?: {
    colors?: string[];
    colorscale?: string | Array<[number, string]>;
    showscale?: boolean;
    line?: {
      color?: string | string[];
      width?: number | number[];
    };
  };
}

Usage Examples by Category

Creating Multi-Trace Plots

// Combining different chart types
const data = [
  {
    x: [1, 2, 3, 4, 5],
    y: [2, 4, 3, 5, 6],
    type: 'scatter',
    mode: 'lines',
    name: 'Line'
  },
  {
    x: [1, 2, 3, 4, 5],
    y: [1, 3, 2, 4, 5],
    type: 'bar',
    name: 'Bars',
    yaxis: 'y2'
  }
];

const layout = {
  yaxis: { title: 'Line Values' },
  yaxis2: { 
    title: 'Bar Values', 
    overlaying: 'y', 
    side: 'right' 
  }
};

await Plotly.newPlot('mixed-chart', data, layout);

Chart Type Selection Guide

  • Scatter/Line: Continuous data, trends, correlations
  • Bar: Categorical comparisons, rankings
  • Pie: Parts of a whole, proportions
  • Box/Violin: Statistical distributions, outliers
  • Histogram: Data frequency distributions
  • Heatmap: 2D intensity data, correlation matrices
  • Contour: Topographical data, mathematical functions
  • 3D Surface: 3D mathematical functions, terrain
  • Candlestick/OHLC: Financial time series
  • Choropleth: Regional geographic data
  • Sankey: Flow processes, network diagrams
  • Treemap/Sunburst: Hierarchical part-to-whole data

Performance Considerations

  • Use WebGL traces (scattergl, scatter3d) for large datasets (>1000 points)
  • Heatmaps and contours can be memory-intensive with large Z matrices
  • 3D traces require WebGL support
  • Geographic traces may need additional topojson data files
  • Consider data sampling or aggregation for very large datasets

Install with Tessl CLI

npx tessl i tessl/npm-plotly-js-dist

docs

animation.md

chart-types.md

core-plotting.md

data-streaming.md

data-updates.md

export-utilities.md

index.md

interactive-components.md

layout-system.md

trace-management.md

tile.json