Plotly.js

Plotly.js is a comprehensive JavaScript data visualization library that enables creation of interactive statistical charts, 3D graphs, scientific visualizations, SVG and tile maps, financial charts, and more. The library serves as the foundation for Python and R plotting ecosystems (Plotly.py and Plotly.R) and provides a complete charting solution with dozens of chart types including bar charts, histograms, heatmaps, contour plots, 3D surfaces, scatter plots, and specialized visualizations like treemaps, sunburst charts, and scientific plots.

Package Information

• Package Name: plotly.js
• Package Type: npm
• Language: JavaScript
• Installation: npm install plotly.js-dist-min (minified) or npm install plotly.js-dist (unminified)

Core Imports

ES6 Module:

import Plotly from 'plotly.js-dist-min';

CommonJS:

var Plotly = require('plotly.js-dist-min');

Script tag (CDN):

<script src="https://cdn.plot.ly/plotly-3.1.0.min.js" charset="utf-8"></script>

Basic Usage

// Create a simple line chart
Plotly.newPlot('myDiv', [{
    x: [1, 2, 3, 4],
    y: [10, 11, 12, 13],
    type: 'scatter'
}], {
    title: 'My First Plot',
    width: 600,
    height: 400
});

// Update the plot
Plotly.restyle('myDiv', 'y', [[16, 18, 20, 17]]);

// Add a new trace
Plotly.addTraces('myDiv', {
    x: [1, 2, 3, 4],
    y: [12, 9, 15, 12],
    type: 'scatter',
    mode: 'markers'
});

Architecture

Plotly.js is built around several key components:

• Core Plotting Engine: The newPlot, react, and redraw methods provide the foundation for creating and updating plots
• Trace System: 58 different trace types covering everything from basic scatter plots to complex 3D visualizations
• Layout System: Comprehensive layout configuration including axes, legends, annotations, and interactive components
• Update System: Efficient methods for modifying existing plots (restyle, relayout, update)
• Event System: Complete event handling for user interactions, animations, and plot lifecycle events
• Export System: Built-in capabilities for exporting plots to various image formats and serialization

Capabilities

Core Plotting Methods

Essential methods for creating, updating, and managing plots. These form the foundation of all plotly.js operations.

function newPlot(gd, data, layout, config);
function react(gd, data, layout, config);
function restyle(gd, astr, val, traces);
function relayout(gd, astr, val);
function redraw(gd);
function purge(gd);
function deleteActiveShape(gd);
function setPlotConfig(config);

Core Plotting Methods

Basic Chart Types

Common chart types for everyday data visualization including scatter plots, bar charts, histograms, pie charts, and box plots.

// Scatter plot trace
{
  x: number[],
  y: number[],
  type: 'scatter',
  mode: 'markers' | 'lines' | 'markers+lines'
}

// Bar chart trace  
{
  x: string[],
  y: number[],
  type: 'bar'
}

Basic Chart Types

Statistical Charts

Advanced statistical visualizations including histograms, box plots, violin plots, and distribution analysis charts.

// Histogram trace
{
  x: number[],
  type: 'histogram',
  nbinsx: number
}

// Box plot trace
{
  y: number[],
  type: 'box',
  name: string
}

Statistical Charts

3D Visualizations

Three-dimensional plotting capabilities including 3D scatter plots, surfaces, meshes, and volume rendering.

// 3D scatter plot
{
  x: number[],
  y: number[],
  z: number[],
  type: 'scatter3d',
  mode: 'markers'
}

// Surface plot
{
  z: number[][],
  type: 'surface'
}

3D Visualizations

Additional Chart Types

Plotly.js includes many additional specialized chart types for specific use cases:

• Scientific Charts: Contour plots, heatmaps, and mathematical visualizations
• Geographic Maps: Choropleth maps, scatter geo plots, and Mapbox integration
• Financial Charts: Candlestick charts, OHLC charts, and waterfall charts
• Specialized Visualizations: Treemaps, sunburst charts, sankey diagrams, and parallel coordinates

These advanced chart types follow similar patterns to the basic charts with specialized trace configurations and data requirements. Each trace type has its own specific attributes and options for customization.

Layout Configuration

Comprehensive layout options for customizing plot appearance, axes, legends, annotations, and interactive components.

interface Layout {
  title?: string | Partial<Title>;
  width?: number;
  height?: number;
  xaxis?: Partial<Axis>;
  yaxis?: Partial<Axis>;
  legend?: Partial<Legend>;
  annotations?: Partial<Annotation>[];
  shapes?: Partial<Shape>[];
}

Layout Configuration

Animation and Frames

Animation capabilities for creating dynamic visualizations with smooth transitions between data states.

function animate(gd, frameOrGroupNameOrFrameList, animationOpts);
function addFrames(gd, frameList, indices);
function deleteFrames(gd, frameList);

Animation methods are part of the core plotting API and are documented in the Core Plotting Methods section.

Events and Interactions

Complete event system for handling user interactions, plot updates, and custom behaviors.

// Event methods
gd.on(event, handler);
gd.once(event, handler);
gd.removeListener(event, handler);

// Common events
'plotly_click'
'plotly_hover'
'plotly_selected'
'plotly_restyle'
'plotly_relayout'

Events and Interactions

Export and Utilities

Export capabilities for generating images, validating data, and working with plot schemas and templates.

function toImage(gd, opts);
function downloadImage(gd, opts);
function validate(data, layout);
function makeTemplate(gd);
function validateTemplate(template);

// PlotSchema methods
PlotSchema.get();
PlotSchema.crawl(attrs, callback, level, attrString);
PlotSchema.isValObject(obj);
PlotSchema.findArrayAttributes(trace);

// Plots utilities
Plots.resize(gd);
Plots.graphJson(gd, dataOnly, layout, data, frames);
Plots.sendDataToCloud(gd, options);

// Snapshot utilities
Snapshot.clone(gd, options);
Snapshot.toSVG(gd, format, scale);
Snapshot.svgToImg(svg, format, scale);

Export and Utilities

Configuration Options

Global configuration options control plot behavior, interactivity, mode bar, and integration with external services.

interface Config {
  staticPlot?: boolean;
  editable?: boolean;
  displayModeBar?: boolean | 'hover';
  responsive?: boolean;
  locale?: string;
}

Common Data Structures

Trace Data Structure

interface Trace {
  type: string;
  x?: any[];
  y?: any[];
  z?: any[];
  mode?: string;
  name?: string;
  marker?: Partial<Marker>;
  line?: Partial<Line>;
  text?: string | string[];
  hovertemplate?: string;
}

Layout Structure

interface Layout {
  title?: string | Partial<Title>;
  width?: number;
  height?: number;
  margin?: Partial<Margin>;
  font?: Partial<Font>;
  paper_bgcolor?: string;
  plot_bgcolor?: string;
}

Configuration Structure

interface Config {
  displayModeBar?: boolean | 'hover';
  modeBarButtonsToRemove?: string[];
  staticPlot?: boolean;
  responsive?: boolean;
  editable?: boolean;
  scrollZoom?: boolean;
  doubleClick?: 'reset' | 'autosize' | 'reset+autosize' | false;
}