or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

animation.mdchart-types.mdcore-plotting.mddata-streaming.mddata-updates.mdexport-utilities.mdindex.mdinteractive-components.mdlayout-system.mdtrace-management.md
tile.json

tessl/npm-plotly-js-dist

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/plotly.js-dist@3.1.x

To install, run

npx @tessl/cli install tessl/npm-plotly-js-dist@3.1.0

index.mddocs/

Plotly.js

Plotly.js is a comprehensive JavaScript data visualization library that enables developers to create interactive charts, graphs, and scientific visualizations directly in web browsers. It supports dozens of chart types including statistical charts, 3D graphs, scientific charts, SVG and tile maps, financial charts, and geographic visualizations.

Package Information

  • Package Name: plotly.js-dist
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install plotly.js-dist

Core Imports

import Plotly from 'plotly.js-dist';

For specific bundles:

import Plotly from 'plotly.js-dist/lib/core';
import Plotly from 'plotly.js-dist/lib/index-basic';
import Plotly from 'plotly.js-dist/lib/index-cartesian';

For CommonJS:

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

Basic Usage

import Plotly from 'plotly.js-dist';

// Create a basic scatter plot
const trace = {
  x: [1, 2, 3, 4],
  y: [10, 11, 12, 13],
  type: 'scatter'
};

const data = [trace];
const layout = {
  title: 'My Plot'
};

// Create the plot
Plotly.newPlot('myDiv', data, layout);

// Update data
Plotly.restyle('myDiv', {'y': [[15, 16, 17, 18]]}, [0]);

// Update layout
Plotly.relayout('myDiv', {'title': 'Updated Plot'});

Architecture

Plotly.js is built around several key components:

  • Modular System: Registry-based loading of trace types, components, and transforms via Plotly.register()
  • Trace System: 48+ chart types each with their own rendering, interaction, and styling capabilities
  • Layout System: Comprehensive layout controls for axes, titles, legends, annotations, and visual styling
  • Component System: Reusable UI components like legends, colorbars, toolbars, and interactive controls
  • Animation System: Frame-based animations with smooth transitions between states
  • Bundle System: Multiple distribution formats from basic (1MB) to full (4.6MB) for different use cases

Capabilities

Core Plotting Functions

Primary functions for creating and manipulating plots. These are the main entry points for all plotting operations.

// Create a new plot from scratch
function newPlot(graphDiv, data, layout, config): Promise<HTMLElement>;

// Smart update with automatic diffing
function react(graphDiv, data, layout, config): Promise<HTMLElement>;

// Force complete redraw
function redraw(graphDiv): Promise<HTMLElement>;

Core Plotting

Data Updates

Functions for updating trace data and layout properties of existing plots without recreating them.

// Update trace properties
function restyle(graphDiv, update, traces): Promise<HTMLElement>;

// Update layout properties  
function relayout(graphDiv, update): Promise<HTMLElement>;

// Combined trace and layout update
function update(graphDiv, traceUpdate, layoutUpdate, traces): Promise<HTMLElement>;

Data Updates

Trace Management

Functions for adding, removing, and reordering traces in existing plots.

// Add new traces
function addTraces(graphDiv, traces, newIndices): Promise<HTMLElement>;

// Remove traces
function deleteTraces(graphDiv, indices): Promise<HTMLElement>;

// Reorder traces
function moveTraces(graphDiv, currentIndices, newIndices): Promise<HTMLElement>;

Trace Management

Data Streaming

Functions for efficiently appending or prepending data to existing traces, ideal for real-time data visualization.

// Append data to traces
function extendTraces(graphDiv, update, indices, maxPoints): Promise<HTMLElement>;

// Prepend data to traces
function prependTraces(graphDiv, update, indices, maxPoints): Promise<HTMLElement>;

Data Streaming

Animation

Functions for creating smooth animated transitions between plot states and managing animation frames.

// Animate between states
function animate(graphDiv, frames, animationOpts): Promise<void>;

// Add animation frames
function addFrames(graphDiv, frameList, indices): Promise<HTMLElement>;

// Remove animation frames
function deleteFrames(graphDiv, frameList): Promise<HTMLElement>;

Animation

Chart Types

48+ trace types covering statistical, scientific, financial, geographic, and 3D visualizations.

// Basic trace types
interface ScatterTrace {
  type: 'scatter';
  x?: number[];
  y?: number[];
  mode?: 'lines' | 'markers' | 'text' | 'lines+markers' | 'lines+text' | 'markers+text' | 'lines+markers+text' | 'none';
}

interface BarTrace {
  type: 'bar';
  x?: string[] | number[];
  y?: number[];
  orientation?: 'v' | 'h';
}

interface PieTrace {
  type: 'pie';
  labels?: string[];
  values?: number[];
}

Chart Types

Layout System

Comprehensive layout controls for plot appearance, axes, legends, annotations, and interactive elements.

interface Layout {
  title?: string | TitleConfig;
  xaxis?: AxisConfig;
  yaxis?: AxisConfig;
  legend?: LegendConfig;
  annotations?: AnnotationConfig[];
  shapes?: ShapeConfig[];
  images?: ImageConfig[];
  width?: number;
  height?: number;
  margin?: MarginConfig;
}

Layout System

Export and Utilities

Functions for exporting plots as images, validating data, and managing plot lifecycle.

// Export plot as image
function toImage(figure, options): Promise<string>;

// Download plot as image file
function downloadImage(graphDiv, options): Promise<void>;

// Validate plot data and layout
function validate(data, layout): ValidationError[];

// Clean up plot resources
function purge(graphDiv): HTMLElement;

Export and Utilities

Interactive Components

Built-in UI components for legends, colorbars, toolbars, and interactive controls.

interface LegendConfig {
  bgcolor?: string;
  bordercolor?: string;
  borderwidth?: number;
  font?: FontConfig;
  orientation?: 'v' | 'h';
  x?: number;
  y?: number;
}

interface ColorbarConfig {
  title?: string;
  titleside?: 'right' | 'top' | 'bottom';
  thickness?: number;
  len?: number;
}

Interactive Components

Bundle Selection

Choose the appropriate bundle for your use case:

  • plotly.js (4.6MB): Full functionality with all trace types
  • plotly-basic.js (1MB): Basic charts (scatter, bar, pie)
  • plotly-cartesian.js (1.3MB): 2D scientific/statistical charts
  • plotly-finance.js (1.1MB): Financial charts (candlestick, OHLC, waterfall)
  • plotly-geo.js (1.2MB): Geographic visualizations
  • plotly-gl2d.js (1.5MB): High-performance 2D charts with WebGL
  • plotly-gl3d.js (1.6MB): 3D visualizations
  • plotly-mapbox.js (1.8MB): Mapbox integration (deprecated)

Configuration

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

Types

// Core data structure for plots
type PlotData = Array<Partial<ScatterTrace | BarTrace | PieTrace | HeatmapTrace | /* ... all other trace types */>>;

// Event data structures
interface PlotlyEvent {
  points: PlotlyEventPoint[];
  event: MouseEvent;
}

interface PlotlyEventPoint {
  data: any;
  fullData: any;
  curveNumber: number;
  pointNumber: number;
  x: any;
  y: any;
}

// Error types
interface ValidationError {
  code: string;
  message: string;
  path: string;
  value: any;
}