Tuesday, October 23, 2018

Published October 23, 2018 by with 0 comment

How To Customize Plotly's Modebar

There's a little bar with buttons that appears when you hover at the top of a plotly graph. It is called the 'modebar'. There is essentially no documentation on customizing it, so I've typed up what I've done to help the next person who needs this.

add button to plotly modebar


In this guide, I will show how to:
  • control which plotly buttons are in the modebar
  • change the behavior of a plotly button
  • add a new button with a new icon
  • style the modebar
I am using plotly.js for all of this but it should translate easily.

Control which buttons are in plotly's modebar

In the plotting methods in plotly, you'll generally see (divid, data, layout) as the parameters. You can add special things in a fourth one if you want. One of those special ones is 'modeBarButtons'. Imagine you have a variable called 'modeBarButtons' that has the options you want. The syntax for Plotly.react is then 'Plotly.react(divid, data, layout, { modeBarButtons: modeBarButtons })'.

What do you put in those? You can put whatever buttons that plotly allows as a simple array of strings. The list as far as I know is:

"zoom2d", "pan2d", "select2d", "lasso2d", "zoomIn2d", "zoomOut2d", "autoScale2d", "resetScale2d", "hoverClosestCartesian", "hoverCompareCartesian", "zoom3d", "pan3d", "resetCameraDefault3d", "resetCameraLastSave3d", "hoverClosest3d", "orbitRotation", "tableRotation", "zoomInGeo", "zoomOutGeo", "resetGeo", "hoverClosestGeo", "toImage", "sendDataToCloud", "hoverClosestGl2d", "hoverClosestPie", "toggleHover", "resetViews", "toggleSpikelines", "resetViewMapbox"

As a simple example, imagine you want only the magnifying glass for zoom2d, the pan for pan2d, and the plotly logo/link. You would set modeBarButtons to:

let modeBarButtons = [[ "zoom2d", "pan2d" ]];

That syntax is an outer array of button groups, and an inner array of buttons. To see that in action, check out this codepen.

Pretty simple and awesome.

Change the behavior of a plotly modebar button

A next step is using one of the plotly buttons to do something other than its default behavior. The syntax is quite simple. Instead of using something like "zoom2d" that looks up a plotly button, just define your own in that array. An example is:

   name: 'Snapshot',
   icon: Plotly.Icons.camera,
   click: () => { alert('new button!'); }

That takes the plotly 'camera' button (normally saves plot as png), names it 'Snapshot', and re-directs its click event to pop up an alert that says 'new button!'. You then just drop that into the array like "zoom2d" in the previous example. To see that in action, check out this codepen.

Here is a list of plotly's modebar icons.

Add a new button to plotly's modebar

Now you want to add a completely new button. An example is a 'lock' icon. You'll need the svg for an icon that you want. I'll use font-awesome's lock icon as an example.To get the svg for an icon, just download font-awesome and go to the svgs file and search by name.

The basic syntax for a custom icon is:


The syntax gets long for this one, so I will just direct you to a sample codepen for it. The basic idea though is the same as above except instead of using one of plotly's existing icons, you define your own then use it.

Style the modebar

Finally, let's do three styling updates:
  1. make the modebar orange
  2. style our custom lock button when clicked
  3. put our custom buttons in their own button group
For #1, we simply update the css for the modebar for our 'plot' div:

#plot .modebar {
  background: orange;

For #2, that's a bit harder as we need to track the state of our button. The basic process is:
  1. track 'clicked' state
  2. define the style for 'clicked'
  3. on click, toggle the 'clicked' style
To do this:
  1. add a variable called 'lockBtnState' that toggles on click
  2. make a class called 'clicked' that sets the path fill to black
  3. in the click event for the button we created, iterate through buttons, and apply or remove the 'clicked' style as needed
This again gets somewhat messy, so it's best to just analyze this codepen. It adds custom styling to the lock button we created that is toggled by clicking it.

NOTE: You cannot simply use plotly's modebar-btn active class. Plotly toggles this automatically. If you want this behavior, make your 'clicked' style identical to their 'active' style.

For #3, that's where the double array from the first section comes in. Check this codepen to see the buttons split into two groups. It's subtle, but there's a slight (should be ~8px) gap between them, and inspecting the html will show that they're in separate modebar groups.

Final niceties

If you want to hide the modebar, add 'displayModeBar: false' as a member in the 4th parameter. If you want to remove the plotly logo from the modebar, add 'displaylogo: false' as a member in the 4th parameter.



Post a Comment