plotly.js

The open source JavaScript graphing library that powers Plotly

Show Sidebar Hide Sidebar
Plotly.js

Event Handlers in plotly.js

Definitions and examples of how to use Plotly.js event handlers to add additional interactive capabilities to Plotly charts.

Plotly graphs emit events prefixed with plotly_ (i.e. 'plotly_click', 'plotly_hover', 'plotly_relayout') when interacted with (clicked, hovered, zoomed). Event handlers can be bound to events using the .on method that is exposed by the plot div object. Please note: it is possible to use jQuery events, but plotly.js no longer bundles jQuery, so we recommend using the plotly.js implementation.

In addition to the event handler, some events emit additional information about the point(s) or plot interacted with. The following documentation organizes Plotly events based on the accessible information emitted with the event: event data, update data, or no additional data. The following page provides a description and example of each Plotly event as well as the structure of the data or update returned with the event.

graphDiv.on('plotly_event', function(){
    	// do something;
	});

Here's a simple example using a Plotly event. Click on a point on the chart below to see an alert triggered by the plotly_click event.

var myPlot = document.getElementById('myDiv'),
    x = [1, 2, 3, 4, 5],
    y = [10, 20, 30, 20, 10],
    data = [{x:x, y:y, type:'scatter',
             mode:'markers', marker:{size:20}
            }],
    layout = {hovermode:'closest',
              title:'Click on Points'
     };

Plotly.newPlot('myDiv', data, layout);

myPlot.on('plotly_click', function(){
    alert('You clicked this Plotly chart!');
});

Many Plotly events emit event data when the event is triggered. Event data is information about the data point related to the event (i.e. the point clicked).
The following events emit event data: plotly_click, plotly_hover, plotly_unhover, plotly_selecting, and plotly_selected.
Event data differs depending on the type of plot the user is interacting with. The event data structure for Cartesian (2D) plots, 3D plots, and maps can be found below, along with examples of each event.

// Cartesian
{
  points: [{
    curveNumber: 1,  // index in data of the trace associated with the selected point
    pointNumber: 1,  // index of the selected point
    x: 1,        // x value
    y: 1,      // y value
    data: {/* */},       // ref to the trace as sent to Plotly.plot associated with the selected point
    fullData: {/* */},   // ref to the trace including all of the default attributes
   xaxis: {/* */},   // ref to x-axis object (i.e layout.xaxis) associated with the selected point
   yaxis: {/* */}    // ref to y-axis object " "
  }, {
    /* similarly for other selected points */
  }]
}

// 3D
{
  points: [{
    curveNumber: 2,  // index in data of the trace associated with the selected point
    pointNumber: 2,  // index of the selected point
    x: 5,        // x value
    y: 600,      // y value
    z: 12,       // z value
    data: {/* */},       // ref to the trace as sent to Plotly.plot associated with the selected point
    fullData: {/* */},   // ref to the trace including all of the default attributes
   xaxis: {/* */},   // ref to x-axis object (i.e layout.xaxis) associated with the selected point
   yaxis: {/* */}    // ref to y-axis object " "
   zaxis: {/* */}    // ref to z-axis object " "
  }, {
    /* similarly for other selected points */
  }]
}

// Maps
{
  points: [{
    curveNumber: 2,  // index in data of the trace associated with the selected point
    pointNumber: 2,  // index of the selected point
    lat: 50,        // latitude value
    lon: -12,      // longtitude value
    data: {/* */},       // ref to the trace as sent to Plotly.plot associated with the selected point
    fullData: {/* */},   // ref to the trace including all of the default attributes
    location:       //
  }, {
    /* similarly for other selected points */
  }]
}

Here's a simple example of using the data returned from the plotly_click event to restyle the graph. After creating a plot, we can change the color of the point clicked on by updating the marker.color array at the index of the point we clicked on then using Plotly.restyle() to apply the update. For more examples of using plotly_click events, see: https://plot.ly/javascript/click-events/

var myPlot = document.getElementById('myDiv'),
    x = [1, 2, 3, 4, 5, 6],
    y = [1, 2, 3, 2, 3, 4],
    colors = ['#00000','#00000','#00000',
              '#00000','#00000','#00000'],
    data = [{x:x, y:y, type:'scatter',
             mode:'markers', marker:{size:16, color:colors}}],
    layout = {
        hovermode:'closest',
        title:'Click on a Point to Change Color
Double Click (anywhere) to Change it Back' }; Plotly.newPlot('myDiv', data, layout); myPlot.on('plotly_click', function(data){ var pn='', tn='', colors=[]; for(var i=0; i < data.points.length; i++){ pn = data.points[i].pointNumber; tn = data.points[i].curveNumber; colors = data.points[i].data.marker.color; }; colors[pn] = '#C54C82'; var update = {'marker':{color: colors, size:16}}; Plotly.restyle('myDiv', update, [tn]); });

Here's a simple example of using the data returned from the plotly_hover and plotly_unhover events to restyle the graph. After creating a plot, we can change the color of the point hovered on by updating the marker.color array at the index of the point we hovered on then using Plotly.restyle() to apply the update. Then we can use plotly_unhover to change the marker.color back to the original color. For more examples of using plotly_hover events, see: https://plot.ly/javascript/hover-events/

var myPlot = document.getElementById('myDiv'),
    x = [1, 2, 3, 4, 5, 6, 7],
    y = [1, 2, 3, 2, 3, 4, 3],
    colors =['#00000','#00000','#00000',
             '#00000','#00000','#00000',
             '#00000'],
    data = [{x:x, y:y,
             type:'scatter',
             mode:'markers', marker:{size:16, color:colors}}],
    layout = {
        hovermode:'closest',
        title:'Hover on a Point
to Change Color' }; Plotly.newPlot('myDiv', data, layout); myPlot.on('plotly_hover', function(data){ var pn='', tn='', colors=[]; for(var i=0; i < data.points.length; i++){ pn = data.points[i].pointNumber; tn = data.points[i].curveNumber; colors = data.points[i].data.marker.color; }; colors[pn] = '#C54C82'; var update = {'marker':{color: colors, size:16}}; Plotly.restyle('myDiv', update, [tn]); }); myPlot.on('plotly_unhover', function(data){ var pn='', tn='', colors=[]; for(var i=0; i < data.points.length; i++){ pn = data.points[i].pointNumber; tn = data.points[i].curveNumber; colors = data.points[i].data.marker.color; }; colors[pn] = '#00000'; var update = {'marker':{color: colors, size:16}}; Plotly.restyle('myDiv', update, [tn]); });

Here's a simple example using the data returned from the plotly_selected event. plotly_selected returns event data for all points selected simultaneously. After creating a scatter plot with random data and two histograms that display the x and y distributions of that random data, we can select points by clicking and dragging on the plot. Upon plotly_selected the histograms will update to display the distribution of the x and y values of the selected points. The color of the scatter plot will be updated as well to highlight the selected points. For more examples of using plotly_slected and plotly_selecting events, see: https://plot.ly/javascript/lasso-selection/

var graphDiv = document.getElementById('graph');
var N = 1000;
var color1 = '#7b3294';
var color1Light = '#c2a5cf';
var colorX = '#ffa7b5';
var colorY = '#fdae61';

function randomArray() {
  var out = new Array(N);
  for(var i = 0; i < N; i++) {
    out[i] = Math.random();
  }
  return out;
}
var x = randomArray();
var y = randomArray();

Plotly.plot(graphDiv, [{
  type: 'scatter',
  mode: 'markers',
  x: x,
  y: y,
  xaxis: 'x',
  yaxis: 'y',
  name: 'random data',
  marker: {color: color1, size: 10}
}, {
  type: 'histogram',
  x: x,
  xaxis: 'x2',
  yaxis: 'y2',
  name: 'x coord dist.',
  marker: {color: colorX}
}, {
  type: 'histogram',
  x: y,
  xaxis: 'x3',
  yaxis: 'y3',
  name: 'y coord dist.',
  marker: {color: colorY}
}], {
  title: 'Lasso around the scatter points to see sub-distributions',
  dragmode: 'lasso',
  xaxis: {
    zeroline: false,
  },
  yaxis: {
    domain: [0.55, 1],
  },
  xaxis2: {
    domain: [0, 0.45],
    anchor: 'y2',
  },
  yaxis2: {
    domain: [0, 0.45],
    anchor: 'x2'
  },
  xaxis3: {
    domain: [0.55, 1],
    anchor: 'y3'
  },
  yaxis3: {
    domain: [0, 0.45],
    anchor: 'x3'
  }
});

graphDiv.on('plotly_selected', function(eventData) {
  var x = [];
  var y = [];

  var colors = [];
  for(var i = 0; i < N; i++) colors.push(color1Light);

  eventData.points.forEach(function(pt) {
    x.push(pt.x);
    y.push(pt.y);
    colors[pt.pointNumber] = color1;
  });

  Plotly.restyle(graphDiv, {
    x: [x, y],
    xbins: {}
  }, [1, 2]);

  Plotly.restyle(graphDiv, 'marker.color', [colors], [0]);
});

The following Plotly events emit update information when the event is triggered: plotly_restyle and plotly_relayout. The update emitted with plotly_restyle is similar across plot types and includes and array containing an object of updated attributes and an array of the trace numbers that were updated.

For Cartesian (2D) plots, plotly_relayout emits the xaxis and yaxis ranges. For 3D plots, layout.scene.camera data is emitted. See the full structures below:

// plotly_restyle update
[
  {update},  // update object -- attribute updated: new value
  [0]       // array of traces updated
]

// plotly_relayout update: Cartesian
//// Upon resizing plot:
{
 xaxis.range[0]: ,
 xaxis.range[1]: ,
 yaxis.range[0]: ,
 yaxis.range[1]:
}
//// Upon autosizing plot:
{
 xaxis.autorange: true,
 yaxis.autorange: true
}

// plotly_relayout update: 3D
{
  scene: {
    center: { // https://plot.ly/javascript/reference/#layout-scene-camera-center
      x: 0,
      y: 0,
      z: 0
    }
  },
  {
    eye: { // https://plot.ly/javascript/reference/#layout-scene-camera-eye
      x: 1.25,
      y: 1.25,
      z: 1.25
    }
  }.
  {
    up: { // https://plot.ly/javascript/reference/#layout-scene-camera-up
      x: 0,
      y: 0,
      z: 1
    }
  }
}

The following Plotly events do not emit additional data or update information: plotly_afterplot, plotly_autosize, plotly_deselect, plotly_doubleclick, plotly_redraw, and plotly_animated. These event handlers can be used to notify or trigger an additional event with the following syntax:

function eventTriggeredHandler() {
   /*  add your event triggered handler here */
}

graphDiv.on('plotly_event', eventTriggeredHandler);

In addition to plotly_click, plotly_doubleclick can be used as an event handle in Plotly charts as well. You may already be familiar with plotly_doubleclick if you regularly use Plotly's zoom and pan functionality, double clicking on the graph will restore the axes ranges after zooming into a specific area. Unlike plotly_click, a plotly_doubleclick is registered upon clicking anywhere on the graph (not just data points), therefore, plotly_doubleclick does not return data. In the following example, we'll build off of our plotly_click example, and reset the color of our data points upon double clicking anywhere on the graph.

var myPlot = document.getElementById('myDiv'),
    x = [1, 2, 3, 4, 5, 6],
    y = [1, 2, 3, 2, 3, 4],
    colors = ['#00000','#00000','#00000',
              '#00000','#00000','#00000'],
    data = [{x:x, y:y, type:'scatter',
             mode:'markers', marker:{size:16, color:colors}}],
    layout = {
        hovermode:'closest',
        title:'Click on a Point to Change Color
Double Click (anywhere) to Change it Back' }; Plotly.newPlot('myDiv', data, layout); myPlot.on('plotly_click', function(data){ var pn='', tn='', colors=[]; for(var i=0; i < data.points.length; i++){ pn = data.points[i].pointNumber; tn = data.points[i].curveNumber; colors = data.points[i].data.marker.color; }; colors[pn] = '#C54C82'; var update = {'marker':{color: colors, size:16}}; Plotly.restyle('myDiv', update, [tn]); }); myPlot.on('plotly_doubleclick', function(data){ var orgColors = ['#00000','#00000','#00000', '#00000','#00000','#00000']; var update = {'marker':{color: orgColors, size:16}}; Plotly.restyle('myDiv', update); });

The event handler: plotly_afterplot, can be used to trigger an event each time a chart is plotted. This also includes re-plotting after the restyling or relayout of a plot. The simple example below logs a console message each time the chart is plotted. Zoom or pan on the graph below to trigger the plotly_afterplot handler.

var myPlot = document.getElementById('myDiv'),
    d3 = Plotly.d3,
    N = 20,
    x = d3.range(N),
    y = d3.range(N).map( d3.random.normal() ),
    data = [{x:x, y:y, type:'scatter',
            mode:'markers', marker:{size:14}}
           ];

Plotly.plot('myDiv', data);

myPlot.on('plotly_afterplot', function(){
    console.log('done plotting');
});

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.