CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-plotly-js

The open source JavaScript graphing library that powers Plotly with comprehensive data visualization capabilities including statistical charts, 3D graphs, scientific visualizations, and interactive plotting features.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

layout.mddocs/

Layout Configuration

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

Capabilities

Basic Layout Properties

Core layout configuration for plot dimensions, colors, and fonts.

/**
 * Basic layout configuration
 */
interface BasicLayout {
  title?: string | Partial<Title>;
  width?: number;
  height?: number;
  autosize?: boolean;
  margin?: Partial<Margin>;
  paper_bgcolor?: string;
  plot_bgcolor?: string;
  font?: Partial<Font>;
  separators?: string;
  hidesources?: boolean;
  showlegend?: boolean;
}

interface Title {
  text: string;
  font?: Partial<Font>;
  x?: number;
  y?: number;
  xref?: string;
  yref?: string;
  xanchor?: 'auto' | 'left' | 'center' | 'right';
  yanchor?: 'auto' | 'top' | 'middle' | 'bottom';
  pad?: Partial<Padding>;
}

interface Margin {
  l?: number;
  r?: number;
  t?: number;
  b?: number;
  pad?: number;
  autoexpand?: boolean;
}

interface Font {
  family?: string;
  size?: number;
  color?: string;
}

interface Padding {
  t?: number;
  r?: number;
  b?: number;
  l?: number;
}

Usage Examples:

// Basic layout configuration
Plotly.newPlot('myDiv', data, {
    title: 'My Chart Title',
    width: 800,
    height: 600,
    margin: { l: 50, r: 50, t: 80, b: 50 },
    paper_bgcolor: 'white',
    plot_bgcolor: '#f8f9fa',
    font: {
        family: 'Arial, sans-serif',
        size: 12,
        color: '#333'
    }
});

// Advanced title configuration
Plotly.newPlot('myDiv', data, {
    title: {
        text: 'Advanced Title with Styling',
        x: 0.5,
        y: 0.95,
        xanchor: 'center',
        font: {
            size: 24,
            color: 'blue'
        }
    }
});

Axis Configuration

Comprehensive axis customization for Cartesian coordinate systems.

/**
 * Axis configuration for x and y axes
 */
interface Axis {
  title?: string | Partial<AxisTitle>;
  type?: 'linear' | 'log' | 'date' | 'category' | 'multicategory';
  autorange?: boolean | 'reversed';
  range?: [any, any];
  fixedrange?: boolean;
  scaleanchor?: string;
  scaleratio?: number;
  constrain?: 'range' | 'domain';
  constraintoward?: 'left' | 'center' | 'right' | 'top' | 'middle' | 'bottom';
  
  // Ticks
  tickmode?: 'linear' | 'array';
  nticks?: number;
  tick0?: number;
  dtick?: number | string;
  tickvals?: any[];
  ticktext?: string[];
  ticks?: '' | 'outside' | 'inside';
  ticklen?: number;
  tickwidth?: number;
  tickcolor?: string;
  tickfont?: Partial<Font>;
  tickangle?: number;
  tickformat?: string;
  tickformatstops?: TickFormatStop[];
  
  // Grid and lines
  showgrid?: boolean;
  gridwidth?: number;
  gridcolor?: string;
  showline?: boolean;
  linewidth?: number;
  linecolor?: string;
  showspikes?: boolean;
  spikecolor?: string;
  spikethickness?: number;
  spikedash?: string;
  spikemode?: string;
  spikesnap?: string;
  
  // Zero line
  zeroline?: boolean;
  zerolinewidth?: number;
  zerolinecolor?: string;
  
  // Labels and positioning
  showticklabels?: boolean;
  side?: 'top' | 'bottom' | 'left' | 'right';
  overlaying?: string;
  position?: number;
  anchor?: string;
  domain?: [number, number];
  
  // Category-specific
  categoryorder?: 'trace' | 'category ascending' | 'category descending' | 'array';
  categoryarray?: any[];
}

interface AxisTitle {
  text: string;
  font?: Partial<Font>;
  standoff?: number;
}

interface TickFormatStop {
  enabled?: boolean;
  dtickrange?: [any, any];
  value?: string;
}

Usage Examples:

// Basic axis configuration
Plotly.newPlot('myDiv', data, {
    xaxis: {
        title: 'Time',
        type: 'date',
        showgrid: true,
        gridcolor: '#e6e6e6'
    },
    yaxis: {
        title: {
            text: 'Value',
            font: { size: 16, color: 'blue' }
        },
        type: 'linear',
        range: [0, 100]
    }
});

// Log scale with custom ticks
Plotly.newPlot('myDiv', data, {
    yaxis: {
        type: 'log',
        tickmode: 'array',
        tickvals: [1, 10, 100, 1000],
        ticktext: ['1', '10', '100', '1K']
    }
});

// Multiple y-axes
Plotly.newPlot('myDiv', data, {
    yaxis: {
        title: 'Primary Y-Axis',
        side: 'left'
    },
    yaxis2: {
        title: 'Secondary Y-Axis',
        side: 'right',
        overlaying: 'y'
    }
});

Legend Configuration

Legend positioning, styling, and behavior options.

/**
 * Legend configuration
 */
interface Legend {
  bgcolor?: string;
  bordercolor?: string;
  borderwidth?: number;
  font?: Partial<Font>;
  orientation?: 'v' | 'h';
  traceorder?: 'normal' | 'reversed' | 'grouped' | 'reversed+grouped';
  tracegroupgap?: number;
  itemsizing?: 'trace' | 'constant';
  itemwidth?: number;
  itemclick?: 'toggle' | 'toggleothers' | false;
  itemdoubleclick?: 'toggle' | 'toggleothers' | false;
  
  // Positioning
  x?: number;
  y?: number;
  xanchor?: 'auto' | 'left' | 'center' | 'right';
  yanchor?: 'auto' | 'top' | 'middle' | 'bottom';
  
  // Grouping
  grouptitlefont?: Partial<Font>;
  
  // Visibility
  visible?: boolean;
}

Usage Examples:

// Basic legend configuration
Plotly.newPlot('myDiv', data, {
    showlegend: true,
    legend: {
        x: 1,
        y: 1,
        xanchor: 'right',
        yanchor: 'top',
        bgcolor: 'rgba(255,255,255,0.8)',
        bordercolor: '#333',
        borderwidth: 1
    }
});

// Horizontal legend at bottom
Plotly.newPlot('myDiv', data, {
    legend: {
        orientation: 'h',
        x: 0.5,
        y: -0.1,
        xanchor: 'center',
        yanchor: 'top'
    }
});

Annotations

Text annotations with arrows and flexible positioning.

/**
 * Annotation configuration
 */
interface Annotation {
  text: string;
  font?: Partial<Font>;
  width?: number;
  height?: number;
  opacity?: number;
  align?: 'left' | 'center' | 'right';
  valign?: 'top' | 'middle' | 'bottom';
  bgcolor?: string;
  bordercolor?: string;
  borderpad?: number;
  borderwidth?: number;
  
  // Positioning
  x?: any;
  y?: any;
  xref?: string;
  yref?: string;
  xanchor?: 'auto' | 'left' | 'center' | 'right';
  yanchor?: 'auto' | 'top' | 'middle' | 'bottom';
  xshift?: number;
  yshift?: number;
  
  // Arrow
  showarrow?: boolean;
  arrowcolor?: string;
  arrowhead?: number;
  startarrowhead?: number;
  arrowside?: 'end' | 'start' | 'end+start' | 'none';
  arrowsize?: number;
  startarrowsize?: number;
  arrowwidth?: number;
  standoff?: number;
  startstandoff?: number;
  ax?: number;
  ay?: number;
  axref?: string;
  ayref?: string;
  
  // Click behavior
  clicktoshow?: false | 'onoff' | 'onout';
  captureevents?: boolean;
}

Usage Examples:

// Basic text annotation
Plotly.newPlot('myDiv', data, {
    annotations: [{
        text: 'Peak Value',
        x: 3,
        y: 25,
        showarrow: true,
        arrowhead: 2,
        arrowcolor: 'red'
    }]
});

// Multiple annotations with different styles
Plotly.newPlot('myDiv', data, {
    annotations: [
        {
            text: 'Start',
            x: 0,
            y: 0,
            xref: 'x',
            yref: 'y',
            showarrow: false,
            bgcolor: 'yellow',
            bordercolor: 'black'
        },
        {
            text: 'End',
            x: 10,
            y: 20,
            showarrow: true,
            ax: -40,
            ay: -40
        }
    ]
});

Shapes

Geometric shapes for highlighting regions and adding visual elements.

/**
 * Shape configuration
 */
interface Shape {
  type: 'circle' | 'rect' | 'path' | 'line';
  visible?: boolean;
  layer?: 'below' | 'above';
  opacity?: number;
  fillcolor?: string;
  fillrule?: 'evenodd' | 'nonzero';
  
  // Line properties
  line?: {
    color?: string;
    width?: number;
    dash?: string;
  };
  
  // Positioning
  x0?: any;
  y0?: any;
  x1?: any;
  y1?: any;
  xref?: string;
  yref?: string;
  
  // Path-specific
  path?: string;
  
  // Template
  name?: string;
  templateitemname?: string;
}

Usage Examples:

// Rectangle shape
Plotly.newPlot('myDiv', data, {
    shapes: [{
        type: 'rect',
        x0: 1,
        y0: 0,
        x1: 3,
        y1: 20,
        fillcolor: 'rgba(255, 0, 0, 0.3)',
        line: {
            color: 'red',
            width: 2
        },
        layer: 'below'
    }]
});

// Line shape
Plotly.newPlot('myDiv', data, {
    shapes: [{
        type: 'line',
        x0: 0,
        y0: 15,
        x1: 10,
        y1: 15,
        line: {
            color: 'green',
            width: 3,
            dash: 'dash'
        }
    }]
});

Images

Embedded images with flexible positioning and sizing.

/**
 * Image configuration
 */
interface Image {
  source: string;
  visible?: boolean;
  opacity?: number;
  
  // Positioning
  x?: any;
  y?: any;
  xref?: string;
  yref?: string;
  xanchor?: 'left' | 'center' | 'right';
  yanchor?: 'top' | 'middle' | 'bottom';
  
  // Sizing
  sizex?: number;
  sizey?: number;
  sizing?: 'fill' | 'contain' | 'stretch';
  
  // Layer
  layer?: 'below' | 'above';
  
  // Template
  name?: string;
  templateitemname?: string;
}

Usage Examples:

// Add logo to plot
Plotly.newPlot('myDiv', data, {
    images: [{
        source: 'https://example.com/logo.png',
        x: 0.9,
        y: 0.9,
        sizex: 0.2,
        sizey: 0.2,
        xref: 'paper',
        yref: 'paper',
        xanchor: 'right',
        yanchor: 'top'
    }]
});

Interactive Components

Update menus, sliders, and range selectors for interactive plots.

/**
 * Update menu configuration
 */
interface UpdateMenu {
  type?: 'dropdown' | 'buttons';
  direction?: 'left' | 'right' | 'up' | 'down';
  active?: number;
  showactive?: boolean;
  buttons: UpdateMenuButton[];
  
  // Positioning
  x?: number;
  y?: number;
  xanchor?: 'auto' | 'left' | 'center' | 'right';
  yanchor?: 'auto' | 'top' | 'middle' | 'bottom';
  
  // Styling
  bgcolor?: string;
  bordercolor?: string;
  borderwidth?: number;
  font?: Partial<Font>;
  
  // Padding
  pad?: Partial<Padding>;
}

interface UpdateMenuButton {
  label?: string;
  method?: 'restyle' | 'relayout' | 'update' | 'animate';
  args?: any[];
  args2?: any[];
  visible?: boolean;
}

/**
 * Slider configuration
 */
interface Slider {
  active?: number;
  steps: SliderStep[];
  
  // Positioning
  x?: number;
  y?: number;
  len?: number;
  xanchor?: 'auto' | 'left' | 'center' | 'right';
  yanchor?: 'auto' | 'top' | 'middle' | 'bottom';
  
  // Styling
  bgcolor?: string;
  bordercolor?: string;
  borderwidth?: number;
  tickcolor?: string;
  ticklen?: number;
  tickwidth?: number;
  
  // Current value
  currentvalue?: {
    visible?: boolean;
    prefix?: string;
    suffix?: string;
    xanchor?: 'left' | 'center' | 'right';
    offset?: number;
    font?: Partial<Font>;
  };
  
  // Transition
  transition?: {
    duration?: number;
    easing?: string;
  };
}

interface SliderStep {
  label?: string;
  method?: 'restyle' | 'relayout' | 'update' | 'animate';
  args?: any[];
  visible?: boolean;
  execute?: boolean;
}

Usage Examples:

// Dropdown menu for changing chart type
Plotly.newPlot('myDiv', data, {
    updatemenus: [{
        type: 'dropdown',
        x: 0.1,
        y: 1.15,
        buttons: [
            {
                label: 'Line',
                method: 'restyle',
                args: [{'type': 'scatter', 'mode': 'lines'}]
            },
            {
                label: 'Bar',
                method: 'restyle',
                args: [{'type': 'bar'}]
            }
        ]
    }]
});

// Slider for data filtering
Plotly.newPlot('myDiv', data, {
    sliders: [{
        active: 0,
        currentvalue: {
            prefix: 'Year: '
        },
        steps: [
            {
                label: '2020',
                method: 'restyle',
                args: [{'visible': [true, false, false]}]
            },
            {
                label: '2021',
                method: 'restyle',
                args: [{'visible': [false, true, false]}]
            }
        ]
    }]
});

Subplot Configuration

Multiple Subplot Types

/**
 * Grid configuration for subplots
 */
interface Grid {
  rows?: number;
  columns?: number;
  subplots?: string[][];
  xaxes?: string[];
  yaxes?: string[];
  roworder?: 'top to bottom' | 'bottom to top';
  pattern?: 'independent' | 'coupled';
  xgap?: number;
  ygap?: number;
  domain?: {
    x?: [number, number];
    y?: [number, number];
  };
  xside?: 'bottom' | 'bottom plot' | 'top plot' | 'top';
  yside?: 'left' | 'left plot' | 'right plot' | 'right';
}

Usage Examples:

// 2x2 subplot grid
Plotly.newPlot('myDiv', data, {
    grid: {
        rows: 2,
        columns: 2,
        pattern: 'independent'
    },
    xaxis: { title: 'X1' },
    xaxis2: { title: 'X2' },
    xaxis3: { title: 'X3' },
    xaxis4: { title: 'X4' },
    yaxis: { title: 'Y1' },
    yaxis2: { title: 'Y2' },
    yaxis3: { title: 'Y3' },
    yaxis4: { title: 'Y4' }
});

Install with Tessl CLI

npx tessl i tessl/npm-plotly-js

docs

3d-charts.md

basic-charts.md

core-plotting.md

events.md

export-utilities.md

index.md

layout.md

statistical-charts.md

tile.json