plotly.js

The open source JavaScript graphing library that powers plotly

  • Open Source.
    These libraries are free forever. Your Pro plan helps keep them top notch.
  • Share Online.
    Share charts, dashboards, Jupyter notebooks, and presentations through our enterprise-grade cloud.
  • Engineering Support.
    Get instant chat support from our awesome engineering team.
Show Sidebar Hide Sidebar

Plotly.js Function Reference

Plotly.js function reference. How to create, update, and modify graphs drawn with Plotly's Javascript Graphing Library.

plotly.js Function Reference

plotDiv.data and plotDiv.layout

The plot data or layout can be retrieved from the <div> element in which the plot was drawn:

var data = [trace1, trace2, trace3];
Plotly.newPlot('examplePlot', data, {title:'My Plot'});

var plotDiv = document.getElementById('examplePlot');
var plotData = plotDiv.data;

Plotly.newPlot

Use newPlot to create a new plot in an empty <div> element. A note on sizing: You can either supply height and width in layout, or give graphDiv a height and width in css.

var trace1 = {
  x: [1999, 2000, 2001, 2002],
  y: [10, 15, 13, 17],
  type: 'scatter'
};
var trace2 = {
  x: [1999, 2000, 2001, 2002],
  y: [16, 5, 11, 9],
  type: 'scatter'
};
var data = [trace1, trace2];
var layout = {
  title: 'Sales Growth',
  xaxis: {
    title: 'Year',
    showgrid: false,
    zeroline: false
  },
  yaxis: {
    title: 'Percent',
    showline: false
  }
};
Plotly.newPlot(graphDiv, data, layout);

// deprecated: calling plot again will add new trace(s) to the plot,
// but will ignore new layout.
var data2 = [{
  x: [1999, 2000, 2001, 2002],
  y: [10, 9, 8, 7],
  type: 'scatter'
}];
var layout2 = {title: 'Revenue'};
Plotly.newPlot(graphDiv, data2, layout2);

See the Pen Plotly.newPlot by plotly (@plotly) on CodePen.


You can hide the link to Plotly's cloud with {showLink: false} as the 4th argument.
Plotly.plot(divid, data, layout, {showLink: false}) There are several other options that you can supply as the fourth argument. See more examples of the configuration options.

Plotly.restyle

A more efficient means of changing attributes in the data array. When restyling, you may choose to have the specified changes effect as many traces as desired. The update is given as a single object and the traces that are effected are given as a list of traces indices. Note, leaving the trace indices unspecified assumes that you want to restyle all the traces.

// restyle a single trace using attribute strings
var update = {
    opacity: 0.4,
    marker.color: 'red'
};
Plotly.restyle(graphDiv, update, 0);

// restyle all traces using attribute strings
var update = {
    opacity: 0.4,
    marker.color: 'red'
};
Plotly.restyle(graphDiv, update);

// restyle two traces using attribute strings
var update = {
    opacity: 0.4,
    marker.color: 'red'
};
Plotly.restyle(graphDiv, update, [1, 2]);

See the Pen Plotly.restyle by plotly (@plotly) on CodePen.


The above examples have applied values across single or multiple traces. However, you can also specify arrays of values to apply to traces in turn.

// restyle the first trace's marker color 'red' and the second's 'green'
var update = {
    marker.color: ['red', 'green']
};
Plotly.restyle(graphDiv, update, [0, 1])

// alternate between red and green for all traces (note omission of traces)
var update = {
    marker.color: ['red', 'green']
};
Plotly.restyle(graphDiv, update)

See the Pen Plotly.restyle Traces in Turn by plotly (@plotly) on CodePen.


In restyle, arrays are assumed to be used in conjunction with the trace indices provided. Therefore, to apply an array as a value, you need to wrap it in an additional array. For example:

// update the color attribute of the first trace so that the markers within the same trace
// have different colors
var update = {
    marker.color: [['red', 'green']]
}
Plotly.restyle(graphDiv, update, [0])

// update two traces with new z data
var update = {z: [[[1,2,3], [2,1,2], [1,1,1]], [[0,1,1], [0,2,1], [3,2,1]]]};
Plotly.restyle(graphDiv, update, [1, 2])

See the Pen Plotly.restyle Arrays by plotly (@plotly) on CodePen.


The term attribute strings is used above to mean flattened (e.g., {marker: {color: 'red'}} vs. {'marker.color': red}). When you pass an attribute string to restyle inside the update object, it’s assumed to mean update only this attribute. Therefore, if you wish to replace and entire sub-object, you may simply specify one less level of nesting.

// replace the entire marker object with the one provided
var update = {
    marker: {color: 'red'}
};
Plotly.restyle(graphDiv, update, [0])

See the Pen Plotly.restyle Attribute strings by plotly (@plotly) on CodePen.


Plotly.relayout

A more efficient means of updating just the layout in a graphDiv. The call signature and arguments for relayout are similar (but simpler) to restyle. Because there are no indices to deal with, arrays need not be wrapped. Also, no argument specifying applicable trace indices is passed in.

// update only values within nested objects
var update = {
    title: 'some new title',
    xaxis.range: [0, 5]
};
Plotly.relayout(graphDiv, update)

See the Pen Plotly.relayout by plotly (@plotly) on CodePen.


Again, caution should be taken regarding flat attribute strings vs sub-objects used with relayout. In the above example, the value for range in xaxis is update. Conversly, below, the xaxis object is replaced with one that only has the range value:

// update an entire nested object with relayout
var update = {
    tile: 'some new title',
    xaxis: {range: [0, 5]}
};
Plotly.relayout(graphDiv, update)

See the Pen Plotly.relayout - xaxis replace by plotly (@plotly) on CodePen.


Plotly.addTraces

This allows you to add new traces to an existing graphDiv at any location in its data array.

// add a single trace to an existing graphDiv
Plotly.addTraces(graphDiv, {y: [2,1,2]});

// add two traces
Plotly.addTraces(graphDiv, [{y: [2,1,2]}, {y: [4, 5, 7]}]);

// add a trace at the beginning of the data array
Plotly.addTraces(graphDiv, {y: [1, 5, 7]}, 0);

See the Pen Plotly.addtraces by plotly (@plotly) on CodePen.


Plotly.deleteTraces

This allows you to remove traces from an existing graphDiv by specifying the indices of the traces to be removed.

// remove the first trace
Plotly.deleteTraces(graphDiv, 0);

// remove the last two traces
Plotly.deleteTraces(graphDiv, [-2, -1]);

See the Pen Plotly.deleteTraces by plotly (@plotly) on CodePen.


Move Traces with Plotly.moveTraces

This allows you to reorder traces in an existing graphDiv. This will change the ordering of the layering and the legend.

// move the first trace (at index 0) the the end of the data array
Plotly.moveTraces(graphDiv, 0);

// move selected traces (at indices [0, 3, 5]) to the end of the data array
Plotly.moveTraces(graphDiv, [0, 3, 5]);

// move last trace (at index -1) to the beginning of the data array (index 0)
Plotly.moveTraces(graphDiv, -1, 0);

// move selected traces (at indices [1, 4, 5]) to new indices [0, 3, 2]
Plotly.moveTraces(graphDiv, [1, 4, 5], [0, 3, 2]);

See the Pen Plotly.moveTraces by plotly (@plotly) on CodePen.


Redraw with Plotly.redraw

Use redraw to trigger a complete recalculation and redraw of the graph. This is not the fastest way to change single attributes, but may be the simplest way. You can make any arbitrary change to the data and layout objects, including completely replacing them, then call redraw.

// make a modification to a graphDiv's data and redraw
graphDiv.data[0].opacity = 0.4;
Plotly.redraw(graphDiv);

// make many modifications and redraw
graphDiv.data[1].marker.color = 'red';
graphDiv.data.push({x: [1,2,3,4], y: [4,3,2,1], mode: 'lines+markers'})
graphDiv.layout.showlegend = false;
Plotly.redraw(graphDiv);

See the Pen Plotly.redraw by plotly (@plotly) on CodePen.


Using events

Plots emit events prefixed with plotly_ when clicked or hovered over, and event handlers can be bound to events using the on method that is exposed by the plot div object. It is possible to use jQuery events, but plotly.js no longer bundles jQuery, so we recommend using the plotly.js implementation.

// You can obtain the plot using document.getElementById('graphDiv')
graphDiv.on('plotly_click', function(data){
    // do something using the event data
});

As well as plotly\_click, there is plotly\_beforehover, plotly\_hover and plotly_unhover.

Purging plotting surface with Plotly.purge

Using purge will clear the div, and remove any Plotly plots that have been placed in it.

// purge will be used on the div that you wish clear of Plotly plots
Plotly.purge(graphDiv);

See the Pen Plotly.purge by plotly (@plotly) on CodePen.


Generating Image Strings with Plotly.toImage

toImage will turn an existing plot into a image string, which could the be used to retrieve a copy of the image.

// Plotly.toImage will turn the plot in the given div into a retrievable image string
// toImage will accept the div as the first argument and an object specifying image properties as the other
Plotly.toImage(graphDiv, {format: 'png', width: 800, height: 600});

See the Pen Plotly.toImage by plotly (@plotly) on CodePen.


Downloading Images of Plots with Plotly.downloadImage

downloadImage will trigger a request to download the image of a Plotly plot.

// downloadImage will accept the div as the first argument and an object specifying image properties as the other
Plotly.downloadImage(graphDiv, {format: 'png', width: 800, height: 600, filename: 'newplot'});

See the Pen Plotly.toImage by plotly (@plotly) on CodePen.


A note on Plotly.plot

Plotly.plot is like newPlot, but it isn't idempotent (you can't call it multiple times in a row).
Still need help?
Contact Us

For guaranteed 24 hour response turnarounds, upgrade to our Premium or Enterprise plans.