You can customize tooltip style, mouse hover effects, toolbar position… This requires usage of css instructions and options. The function girafe has an argument options, a list of options to customize the rendering. These effects will be defined by function calls, i.e. opts_tooltip(), opts_toolbar(), …

library(ggplot2)
library(ggiraph)

dataset <- mtcars
dataset$carname <- row.names(dataset)
gg_scatter <- ggplot(dataset, 
    aes(x = disp, y = qsec, tooltip = carname, 
        data_id = carname, color= wt) ) + 
    geom_point_interactive(size=3) + 
  labs(title = "mouse over points") + 
  theme_minimal() + theme(
    plot.background = element_blank(),
    panel.background = element_blank()
  )

Size options

By default the size of the graph is automatically adjusted to 100% of the width of the web page containing it.

Graphic will be resized if its container is resized.

This behavior can be controlled by using the opts_sizing function.

The percentage of the width to be used can be defined with the width parameter which takes a value between 0 and 1.

girafe(ggobj = gg_scatter, 
  options = list(
    opts_sizing(rescale = TRUE, width = .7) )
  )

This resizing can also be undone using the rescale argument with the value FALSE. In this case, the use of width will have no effect.
To control the actual size of the graph, use the width_svg and height_svg parameters of the girafe function, the expected values are expressed in inches.

girafe(ggobj = gg_scatter, width_svg = 7, height_svg = 4, 
  options = list(
    opts_sizing(rescale = FALSE) )
  )

Tooltip options

Tooltip can be customized with function opts_tooltip().

Tooltip position

The arguments offx and offy of function opts_tooltip are used to offset tooltip position.

Default offset is 10 pixels horizontally to the mouse position (offx=10) and 0 pixels vertically (offy=0).

girafe(ggobj = gg_scatter, 
  options = list(
    opts_tooltip(offx = 20, offy = 20)) )

If argument use_cursor_pos is set to FALSE, the tooltip will be fixed at offx and offy.

girafe(ggobj = gg_scatter, 
  options = list(opts_tooltip(offx = 60, 
     offy = 60, use_cursor_pos = FALSE)) )

Tooltip style

The opts_tooltip function has an argument named css. It can be used to add css declarations to customize tooltip rendering.

Each css declaration includes a property name and an associated value. Property names and values are separated by colons and name-value pairs always end with a semicolon. For example color:gray;text-align:center;. Common properties are :

  • background-color: background color
  • color: elements color
  • border-style, border-width, border-color: border properties
  • width, height: size of tooltip
  • padding: space around content

Tooltip opacity can be defined with the argument opacity (default to 0.9).

Let’s custom tooltip as:

  • italic font
  • no background color
tooltip_css <- "background-color:transparent;font-style:italic;"

Now print the girafe graphic:

girafe(ggobj = gg_scatter, 
  options = list(
    opts_tooltip(css = tooltip_css),
    opts_sizing(width = .7) ) )

Now, let’s add a gray rectangle with round borders and a few other details to make it less crude:

tooltip_css <- "background-color:gray;color:white;font-style:italic;padding:10px;border-radius:5px;"
girafe(ggobj = gg_scatter, 
  options = list(opts_tooltip(css = tooltip_css),
                 opts_sizing(width = .7) ) )

Do not surround css value by curly braces, girafe function takes care of that.

Auto coloring

In function opts_tooltip, set argument use_fill to TRUE and the background color of tooltip will always use use elements fill property to color tooltip.

Argument use_stroke is to be used to apply the same to the border color of the tooltip.

girafe(ggobj = gg_scatter, 
  options = list(opts_tooltip(use_fill = TRUE),
                 opts_sizing(width = .7) ) )

Package ggiraph enable elements to be dynamic when mouse is hovering over them. This is possible when an element is associated with a data_id.

The dynamic aspect of elements can be defined with css code by the user. There are several ways to define these settings.

Hover effects

The elements that are associated with a data_id are animated when the mouse hovers over them. These animations can be configured using the following functions:

  • opts_hover for the animation of panel elements
  • opts_hover_key for the animation of the elements of the legends
  • opts_hover_theme for the animation of the elements of the theme

These functions all have a css argument that defines by css instructions the style to use when the mouse passes over them. css here is relative to SVG elements. SVG attributes are listed here. Common properties are:

  • fill: background color
  • stroke: color
  • stroke-width: border width
  • r: circle radius (no effect if Firefox is used).

To fill elements in red, opts_hover call should be used as below:

girafe(ggobj = gg_scatter, 
  options = list(
    opts_hover(css = "fill:red;")
  ) )

Another option can be used to alter aspect of non hovered elements. It is very useful to highlight hovered elements when the density of the elements is high by fixing less opacity on the other elements.

girafe(ggobj = gg_scatter, 
  options = list(
    opts_hover_inv(css = "opacity:0.1;"),
    opts_hover(css = "fill:red;")
  ) )

Detailled control

Now there are cases where css expressions will have to be configured with more caution.

Let’s have a look at the following example ; if you put your mouse hover points or text, you will see that the animation is not adapted to the text. Text should instead be animated with another css property.

gg_scatter2 <- ggplot(dataset, aes(x = disp, y = qsec, label = carname, 
  data_id = carname, color= wt) ) + 
  geom_point_interactive(size=3) + 
  geom_text_interactive(vjust = 2) +
  theme_minimal()

girafe(ggobj = gg_scatter2, 
  options = list(
    opts_hover(css = "fill:red;stroke:black;")
  ) )

Function girafe_css is to be used in that case, it allows to specify individual styles for various SVG elements.

girafe(ggobj = gg_scatter2, 
  options = list(
    opts_hover(
    css = girafe_css(
      css = "fill:purple;stroke:black;",
      text = "stroke:none;fill:red;"
    )
  )
  ) )

Zoom

You can activate zoom; set zoom_max (maximum zoom factor) to a value greater than 1. If the argument is greater than 1, a toolbar will appear when mouse will be over the graphic.

Click on the icons in the toolbar to activate or desactivate the zoom.

girafe(ggobj = gg_scatter, 
  options = list(
    opts_sizing(width = .7),
    opts_zoom(max = 5))
  )

Toolbar

A toolbar is added by default to the graphs at the top right. It contains at least the download button for the PNG version of the graph.

It will contain other elements depending on the options used. If a zoom has been configured, the zoom options will be added to it. If a selection is configured and the graph is in a shiny application, the selection options will be added to it, i.e. selection and anti-selection.

Toolbar position cann be defined with function opts_toolbar() and argument position.

girafe(ggobj = gg_scatter, 
  options = list(
    opts_sizing(width = .7),
    opts_toolbar(position = "bottomright") )
  )

Also ‘save as png’ button can be desactivated by using argument saveaspng.
saveaspng relies on JavaScript promises, so any browsers that don’t natively support the standard Promise object will need to have a polyfill (e.g. Internet Explorer with version less than 11 will need it).

girafe(ggobj = gg_scatter, 
  options = list(
    opts_sizing(width = .7),
    opts_toolbar(saveaspng = FALSE) )
  )