plotly.js

The open source JavaScript graphing library that powers Plotly

Show Sidebar Hide Sidebar
Plotly.js

Plotly.js Function Reference in plotly.js

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

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

Creates 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.plot

Plotly.plot is like newPlot, but it isn't idempotent (you can't call it multiple times in a row).

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.

Finally, you may wish to selectively reset or ignore certain properties when restyling. This may be useful when specifying multiple properties for multiple traces so that you can carefully target what is and is not affected. In general `null` resets a property to the default while `undefined` applies no change to the current state.

// Set the first trace's line to red, the second to the default, and ignore the third
Plotly.restyle(graphDiv, {
  'line.color': ['red', null, undefined]
}, [0, 1, 2])

See the Pen null vs. undefined in Plotly.restyle 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', // updates the title
    'xaxis.range': [0, 5],   // updates the xaxis range
    'yaxis.range[1]': 15     // updates the end of the yaxis range
};
Plotly.relayout(graphDiv, update)
http://codepen.io/anon/pen/BLxvJK

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

Plotly.update

A method for updating both the data and layout objects in a graphDiv.

var data_update = {
    marker: {color: 'red'}
};
var layout_update = {
    title: 'some new title', // updates the title
};
Plotly.update(graphDiv, data_update, layout_update)

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.

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.

Plotly.extendTraces

This allows you to add data to traces in an existing graphDiv.

// extend one trace
Plotly.extendTraces(graphDiv, {y: [[rand()]]}, [0])

// extend multiple traces
Plotly.extendTraces(graphDiv, {y: [[rand()], [rand()]]}, [0, 1])

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

Plotly.prependTraces

This allows you to prepend data to an existing trace graphDiv.

// prepend one trace
Plotly.prependTraces(graphDiv, {y: [[rand()]]}, [0])

// prepend multiple traces
Plotly.prependTraces(graphDiv, {y: [[rand()], [rand()]]}, [0, 1])

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

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.

Plotly.toImage

toImage will generate a promise to an image of the plot in data URL format.

// Plotly.toImage will turn the plot in the given div into a data URL string
// toImage takes the div as the first argument and an object specifying image properties as the other
Plotly.toImage(graphDiv, {format: 'png', width: 800, height: 600}).then(function(dataUrl) {
    // use the dataUrl
})

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

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.

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. For more information and examples of how to use Plotly events see: https://plot.ly/javascript/plotlyjs-events/.

plotly.js runs on all SVG-compatible browsers

Still need help?
Contact Us

For guaranteed 24 hour response turnarounds, upgrade to a Developer Support Plan.