Configuration in R

How to set the configuration options of figures using the Plotly R graphing library.

New to Plotly?

Plotly is a free and open-source graphing library for R. We recommend you read our Getting Started guide for the latest installation or upgrade instructions, then move on to our Plotly Fundamentals tutorials or dive straight in to some Basic Charts tutorials.

Configuration Options

The config() method sets the configuration options for your figure.

You can set the configuration options for your figure by passing a list to this parameter which contains the options you want to set.

If you don't set an option's value, it will automatically be set to the default value for that option.

For the complete list of configuration options and their defaults see: https://github.com/plotly/plotly.js/blob/master/src/plotapi/plotconfig.js

Enabling Scroll Zoom

This option allows users to zoom in and out of figures using the scroll wheel on their mouse and/or a two-finger scroll.

library(plotly) 

fig <- plot_ly()%>%
  add_trace(x = c(1, 2, 3), y = c(1, 3, 1), type = 'scatter', mode = 'lines+markers')
config(fig, scrollZoom = TRUE)%>%layout(plot_bgcolor='#e5ecf6',
          xaxis = list(
            zerolinecolor = '#ffff',
            zerolinewidth = 2,
            gridcolor = 'ffff'),
          yaxis = list(
            zerolinecolor = '#ffff',
            zerolinewidth = 2,
            gridcolor = 'ffff')
          )

Turning Off Responsiveness

By default, figures you create with the plotly package are responsive. Responsive figures automatically change their height and width when the size of the window they are displayed in changes. This is true for figures which are displayed in web browsers on desktops and mobile, Jupyter Notebooks, and other rendering environments.

Try resizing your browser window to see this behavior in effect on this page.

If you would like to disable this default behavior and force your figures to always have the same height and width regardless of the window size, set the value of the responsive key to FALSE in your figure's configuration dictionary.

library(plotly) 

fig <- plot_ly()%>%
  add_trace(x = c(1, 2, 3), y = c(1, 3, 1), type = 'scatter', mode = 'lines+markers')
config(fig, responsive = FALSE)%>%layout(plot_bgcolor='#e5ecf6',
          xaxis = list(
            zerolinecolor = '#ffff',
            zerolinewidth = 2,
            gridcolor = 'ffff'),
          yaxis = list(
            zerolinecolor = '#ffff',
            zerolinewidth = 2,
            gridcolor = 'ffff')
          )

Making A Static Chart

library(plotly) 

fig <- plot_ly()%>%
  add_trace(x = c(1, 2, 3), y = c(1, 3, 1), type = 'scatter', mode = 'lines+markers')
config(fig, staticPlot = TRUE)%>%layout(plot_bgcolor='#e5ecf6',
          xaxis = list(
            zerolinecolor = '#ffff',
            zerolinewidth = 2,
            gridcolor = 'ffff'),
          yaxis = list(
            zerolinecolor = '#ffff',
            zerolinewidth = 2,
            gridcolor = 'ffff')
          )

Forcing The Modebar to Always Be Visible

When users hover over a figure generated with plotly, a modebar appears in the top-right of the figure. This presents users with several options for interacting with the figure.

By default, the modebar is only visible while the user is hovering over the chart. If you would like the modebar to always be visible regardless of whether or not the user is currently hovering over the figure, set the displayModeBar attribute in the configuration of your figure to true.

library(plotly) 

fig <- plot_ly()%>%
  add_trace(x = c(1, 2, 3), y = c(1, 3, 1), type = 'scatter', mode = 'lines+markers')
config(fig, displayModeBar = TRUE)%>%layout(plot_bgcolor='#e5ecf6',
          xaxis = list(
            zerolinecolor = '#ffff',
            zerolinewidth = 2,
            gridcolor = 'ffff'),
          yaxis = list(
            zerolinecolor = '#ffff',
            zerolinewidth = 2,
            gridcolor = 'ffff')
          )

Preventing the Modebar from Appearing

When users hover over a figure generated with plotly, a modebar appears in the top-right of the figure. This presents users with several options for interacting with the figure.

By default, the modebar is only visible while the user is hovering over the chart. If you would like the modebar to never be visible, then set the displayModeBar attribute in the config of your figure to FALSE.

library(plotly) 

fig <- plot_ly()%>%
  add_trace(x = c(1, 2, 3), y = c(1, 3, 1), type = 'scatter', mode = 'lines+markers')
config(fig, displayModeBar = FALSE)%>%layout(plot_bgcolor='#e5ecf6',
          xaxis = list(
            zerolinecolor = '#ffff',
            zerolinewidth = 2,
            gridcolor = 'ffff'),
          yaxis = list(
            zerolinecolor = '#ffff',
            zerolinewidth = 2,
            gridcolor = 'ffff')
          )

Hiding the Plotly Logo on the Modebar

library(plotly) 

fig <- plot_ly()%>%
  add_trace(x = c(1, 2, 3), y = c(1, 3, 1), type = 'scatter', mode = 'lines+markers')
config(fig, displaylogo = FALSE)%>%layout(plot_bgcolor='#e5ecf6',
          xaxis = list(
            zerolinecolor = '#ffff',
            zerolinewidth = 2,
            gridcolor = 'ffff'),
          yaxis = list(
            zerolinecolor = '#ffff',
            zerolinewidth = 2,
            gridcolor = 'ffff')
          )

Customizing Modebar "Download Plot" Button

The camera icon on the modebar causes a static version of the figure to be downloaded via the user's browser. The default behaviour is to download a PNG of size 700 by 450 pixels.

This behavior can be controlled via the toImageButtonOptions configuration key.

library(plotly) 

fig <- plot_ly()%>%
  add_trace(x = c(1, 2, 3), y = c(1, 3, 1), type = 'bar')
config(fig, toImageButtonOptions = list(format= 'svg', # one of png, svg, jpeg, webp
                                        filename= 'custom_image',
                                        height= 500,
                                        width= 700,
                                        scale= 1 ))%>%layout(plot_bgcolor='#e5ecf6',
          xaxis = list(
            zerolinecolor = '#ffff',
            zerolinewidth = 2,
            gridcolor = 'ffff'),
          yaxis = list(
            zerolinecolor = '#ffff',
            zerolinewidth = 2,
            gridcolor = 'ffff')
          )

Figures can be set to download at the currently-rendered size by setting height and width to NULL:

library(plotly) 

fig <- plot_ly()%>%
  add_trace(x = c(1, 2, 3), y = c(1, 3, 1), type = 'bar')
config(fig, toImageButtonOptions = list(height= NULL,
                                        width= NULL))%>%layout(plot_bgcolor='#e5ecf6',
          xaxis = list(
            zerolinecolor = '#ffff',
            zerolinewidth = 2,
            gridcolor = 'ffff'),
          yaxis = list(
            zerolinecolor = '#ffff',
            zerolinewidth = 2,
            gridcolor = 'ffff')
          )

Removing Modebar Buttons

To delete buttons from the modebar, pass an array of strings containing the names of the buttons you want to remove to the modeBarButtonsToRemove attribute in the figure's configuration dictionary. Note that different chart types have different default modebars. The following is a list of all the modebar buttons and the chart types they are associated with:

High-level: zoom, pan, select, zoomIn, zoomOut, autoScale, resetScale
2D: zoom2d, pan2d, select2d, lasso2d, zoomIn2d, zoomOut2d, autoScale2d, resetScale2d
2D Shape Drawing: drawline, drawopenpath, drawclosedpath, drawcircle, drawrect, eraseshape
3D: zoom3d, pan3d, orbitRotation, tableRotation, handleDrag3d, resetCameraDefault3d, resetCameraLastSave3d, hoverClosest3d
Cartesian: hoverClosestCartesian, hoverCompareCartesian
Geo: zoomInGeo, zoomOutGeo, resetGeo, hoverClosestGeo
Other: hoverClosestGl2d, hoverClosestPie, toggleHover, resetViews, toImage, sendDataToCloud, toggleSpikelines, resetViewMapbox

library(plotly) 

fig <- plot_ly()%>%
  add_trace(x = c(1, 2, 3), y = c(1, 3, 1), type = 'scatter', mode = 'lines+markers')
config(fig, modeBarButtonsToRemove = c('zoom2d','pan2d'))%>%layout(plot_bgcolor='#e5ecf6',
          xaxis = list(
            zerolinecolor = '#ffff',
            zerolinewidth = 2,
            gridcolor = 'ffff'),
          yaxis = list(
            zerolinecolor = '#ffff',
            zerolinewidth = 2,
            gridcolor = 'ffff')
          )

You can also use a pipe instead of the approach used above:

library(plotly) 

fig <- plot_ly()%>%
  add_trace(x = c(1, 2, 3), y = c(1, 3, 1), type = 'scatter', mode = 'lines+markers')%>%
  config(modeBarButtonsToRemove = c('zoom2d','pan2d'))%>%layout(plot_bgcolor='#e5ecf6',
          xaxis = list(
            zerolinecolor = '#ffff',
            zerolinewidth = 2,
            gridcolor = 'ffff'),
          yaxis = list(
            zerolinecolor = '#ffff',
            zerolinewidth = 2,
            gridcolor = 'ffff')
          )
fig

Add optional shape-drawing buttons to modebar

Some modebar buttons of Cartesian plots are optional and have to be added explicitly, using the modeBarButtonsToAdd config attribute. These buttons are used for drawing or erasing shapes. See the tutorial on shapes and shape drawing for more details.

library(plotly) 
data(iris) 

fig <- plot_ly(data = iris, x = ~Petal.Width, y = ~Sepal.Length, color = ~Species,  
               type = "scatter", mode = "markers")%>% 
  layout(title="A Plotly Figure", legend=list(title=list(text='species'))) 

fig <- fig %>% layout(dragmode='drawopenpath', 
                      newshape=list(line = list(color='cyan')), 
                      title = 'Draw a path to separate versicolor and virginica') 

#Add modebar buttons 
config(fig,modeBarButtonsToAdd = list('drawline', 
                                 'drawopenpath', 
                                 'drawclosedpath', 
                                 'drawcircle', 
                                 'drawrect', 
                                 'eraseshape')) %>%layout(plot_bgcolor='#e5ecf6',
          xaxis = list(
            zerolinecolor = '#ffff',
            zerolinewidth = 2,
            gridcolor = 'ffff'),
          yaxis = list(
            zerolinecolor = '#ffff',
            zerolinewidth = 2,
            gridcolor = 'ffff')
          )

You can also use a pipe instead of the approach used above:

library(plotly) 
data(iris) 

fig <- plot_ly(data = iris, x = ~Petal.Width, y = ~Sepal.Length, color = ~Species,  
               type = "scatter", mode = "markers")%>% 
  layout(title="A Plotly Figure", legend=list(title=list(text='species'))) 

fig <- fig %>% layout(dragmode='drawopenpath', 
                      newshape=list(line = list(color='cyan')), 
                      title = 'Draw a path to separate versicolor and virginica') 

#Add modebar buttons 
fig <- fig %>%  
  config(modeBarButtonsToAdd = c('drawline', 
                                 'drawopenpath', 
                                 'drawclosedpath', 
                                 'drawcircle', 
                                 'drawrect', 
                                 'eraseshape')) %>%layout(plot_bgcolor='#e5ecf6',
          xaxis = list(
            zerolinecolor = '#ffff',
            zerolinewidth = 2,
            gridcolor = 'ffff'),
          yaxis = list(
            zerolinecolor = '#ffff',
            zerolinewidth = 2,
            gridcolor = 'ffff')
          )

fig

Double-Click Delay

Sets the maximum delay between two consecutive clicks to be interpreted as a double-click in milliseconds. This is the time interval between first mousedown and second mouseup. The default timing is 300 ms (less than half a second). This setting propagates to all on-subplot double clicks (except for geo and mapbox).

library(plotly) 

fig <- plot_ly()%>%
  add_trace(y = c(3, 5, 3, 2), x = c("2019-09-02", "2019-10-10", "2019-11-12", "2019-12-22"), 
            type = 'bar',
            texttemplate = "%{label}",
            textposition = "inside")%>%
  layout(xaxis = list(type = 'date'))

config(fig, doubleClickDelay= 1000)%>%layout(plot_bgcolor='#e5ecf6',
          xaxis = list(
            zerolinecolor = '#ffff',
            zerolinewidth = 2,
            gridcolor = 'ffff'),
          yaxis = list(
            zerolinecolor = '#ffff',
            zerolinewidth = 2,
            gridcolor = 'ffff')
          )

Configuring Figures in Dash Apps

The same configuration dictionary that you pass to the config parameter can also be passed to the config property of a dcc.Graph component.

Reference

See config options at https://github.com/plotly/plotly.js/blob/master/src/plotapi/plotconfig.js#L6

What About Dash?

Dash for R is an open-source framework for building analytical applications, with no Javascript required, and it is tightly integrated with the Plotly graphing library.

Learn about how to install Dash for R at https://dashr.plot.ly/installation.

Everywhere in this page that you see fig, you can display the same figure in a Dash for R application by passing it to the figure argument of the Graph component from the built-in dashCoreComponents package like this:

library(plotly)

fig <- plot_ly() 
# fig <- fig %>% add_trace( ... )
# fig <- fig %>% layout( ... ) 

library(dash)
library(dashCoreComponents)
library(dashHtmlComponents)

app <- Dash$new()
app$layout(
    htmlDiv(
        list(
            dccGraph(figure=fig) 
        )
     )
)

app$run_server(debug=TRUE, dev_tools_hot_reload=FALSE)