2  Customizing girafe animations

You can customize tooltip style, mouse hover effects, toolbar position and many details.

This requires usage of css instructions and options. The function girafe has an argument options, a list of options to customize the rendering with calls to dedicated functions, i.e. opts_tooltip(), opts_toolbar(), opts_hover(), …

We will use the following graphic to illustrate available options:

library(tidyverse)

mtcars_db <- rownames_to_column(mtcars, var = "carname")

gg_scatter <- ggplot(
  data = mtcars_db,
  mapping = aes(
    x = disp, y = qsec, color = wt,
    # here we add iteractive aesthetics
    tooltip = carname, data_id = carname
  )) + geom_point_interactive(
    size = 3, hover_nearest = TRUE)
gg_scatter

2.1 Global option definition

Default values are frequently used when creating “girafe” objects. It is recommended to specify them only once in the R session in order to obtain homogeneous interactive graphics.

When a ‘girafe’ is created (when function girafe() is called), some default values are used as the css for hover effects or css for tooltips.

User can read them with function get_flextable_defaults().

z <- girafe_defaults()
z$opts_hover$css
[1] ".hover_data_SVGID_ { fill:#f24f26;stroke:#333333;cursor:pointer; }\ntext.hover_data_SVGID_ { stroke:none;fill:#f24f26; }\ncircle.hover_data_SVGID_ { fill:#f24f26;stroke:#333333; }\nline.hover_data_SVGID_, polyline.hover_data_SVGID_ { fill:none;stroke:#f24f26; }\nrect.hover_data_SVGID_, polygon.hover_data_SVGID_, path.hover_data_SVGID_ { fill:#f24f26;stroke:none; }\nimage.hover_data_SVGID_ { stroke:#f24f26; }"

These default properties will be used when creating the graphics. They can be updated with function set_girafe_defaults().

To set global options that apply to all graphics and get homogeneous interactive behavior and design, call set_girafe_defaults() at the beginning of your R Markdown document or R script.

css_default_hover <- girafe_css_bicolor(primary = "yellow", secondary = "red")

set_girafe_defaults(
  opts_hover = opts_hover(css = css_default_hover),
  opts_zoom = opts_zoom(min = 1, max = 4),
  opts_tooltip = opts_tooltip(css = "padding:3px;background-color:#333333;color:white;"),
  opts_sizing = opts_sizing(rescale = TRUE),
  opts_toolbar = opts_toolbar(saveaspng = FALSE, position = "bottom", delay_mouseout = 5000)
)

girafe(ggobj = gg_scatter)

2.2 Tooltip options

Tooltip visual aspect and position can be defined with function opts_tooltip().

2.2.1 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
  ))
)

2.2.2 Tooltip style

The function opts_tooltip() 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
  • opacity: background opacity (default to 0.9)

Let’s add a pink rectangle with round borders and a few other details to make it nice:

tooltip_css <- "background-color:#d8118c;color:white;padding:5px;border-radius:3px;"
girafe(
  ggobj = gg_scatter,
  options = list(
    opts_tooltip(css = tooltip_css, opacity = 1),
    opts_sizing(width = .7)
  )
)

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

2.2.3 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 + scale_color_viridis_c(),
  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.

2.3 Hover effects

The elements that are associated with a data_id are animated when the mouse hovers over them. Clicks and hover actions on these elements are also available as reactive values in shiny applications.

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 via 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 yellow and add a black stroke, opts_hover call should be used as below:

girafe(
  ggobj = gg_scatter,
  options = list(
    opts_hover(css = "fill:yellow;stroke:black;stroke-width:3px;")
  )
)

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.

dat <- readRDS("data/species-ts.RDS")

gg <- ggplot(dat, aes(x = date, y = score, 
                      colour = species, group = species)) +
  geom_line_interactive(aes(tooltip = species, data_id = species)) +
  scale_color_viridis_d() + 
  labs(title = "move mouse over lines")

x <- girafe(ggobj = gg, width_svg = 8, height_svg = 6,
  options = list(
    opts_hover_inv(css = "opacity:0.1;"),
    opts_hover(css = "stroke-width:2;")
  ))
x

2.3.1 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 <- ggplot(head(mtcars_db), aes(
  x = disp, y = qsec, label = carname,
  data_id = carname, color = wt
)) +
  geom_text_interactive(vjust = 2) +
  theme_minimal()

girafe(
  ggobj = gg,
  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,
  options = list(
    opts_hover(
      css = girafe_css(
        css = "fill:purple;stroke:black;",
        text = "stroke:none;fill:red;"
      )
    )
  )
)

2.4 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)
  )
)