ggiraph-book

Author

David Gohel

Published

August 27, 2025

Preface

The ‘ggiraph’ package lets you create dynamic and interactive graphics: dynamic with animations and tooltips, interactive in shiny applications where events/interactions with ggiraph graphic are made available as reactive values.

Under the hood, ‘ggiraph’ is an ‘htmlwidget’ and a ‘ggplot2’ extension. It allows graphics to be interactive, by exporting them as SVG documents and using special attributes on the various elements. The package is also containing an R graphic device dedicated to SVG, it’s beeing used to produce ‘ggiraph’ graphics but can be used to produce standard SVG graphics.

Why using ‘ggiraph’

  • You want to provide your readers with more information than the basic information available; you can display a tooltip when the user’s mouse is on a graphical element, you can also visually animate elements with the same attribute when the mouse passes over a graphical element, and finally you can link a JavaScript action to the click, such as opening a hypertext link.
  • You want to allow users of a Shiny application to select graphical elements; for example, you can make the points of a scatter plot selectable and available as a reactive value from the server part of your application. With Shiny, ‘ggiraph’ allows interaction with graph elements, legends elements, titles and ggplot theme elements from the server part; each selection is available as a reactive value.

How does it compare to plotly

A common question is how ggiraph compares to plotly::ggplotly(). Both add interactivity to ggplot2 graphics, but with different approaches:

  • ggplot2 fidelity: ggiraph produces SVG with an actual R graphics device (the same rendering pipeline as pdf() or png()). The output is pixel-identical to your static ggplot. ggplotly() re-interprets the ggplot object in JavaScript, which can lead to visual differences — some geoms, themes or extensions may not translate correctly.
  • Learning curve: ggplotly() works instantly — wrap any existing ggplot and you get tooltips, zoom and pan with no extra code. ggiraph requires the user to explicitly specify interactive aesthetics (tooltip, data_id, onclick), which takes more effort up front but gives full control over what is interactive and how.
  • Interactivity model: ggiraph provides tooltip, hover animation, element selection (single/multiple/lasso) and onclick actions. In Shiny, selections and hover events are available as reactive values for all parts of the graphic (panel, legend, theme). plotly provides built-in zoom, pan, hover and click events.
  • Selection as a basket: with ggiraph, users can build a selection incrementally — clicking elements adds or removes them from a basket (single or multiple mode), and lasso selection lets them draw a region to select/unselect many elements at once. The current selection is always available as a Shiny reactive value. This basket-like behavior is central to ggiraph and has no direct equivalent in plotly.
  • Shiny integration: ggiraph is designed around Shiny — element selections via click or lasso, programmatic CSS class manipulation, and linked legend/geometry interactions are first-class features. plotly offers Shiny integration through plotly::event_data().

In short, ggplotly() is the quickest path to an interactive graphic. ggiraph requires more explicit setup but gives you pixel-perfect ggplot2 rendering, a powerful selection model for Shiny, and full control over every interactive behavior.

How does it work

It extends ggplot2 with:

  • interactive geom functions: geom_point_interactive(), geom_col_interactive, etc.
  • interactive scale functions: scale_color_continuous_interactive(), scale_fill_manual_interactive(), etc.
  • interactive facet functions: facet_wrap_interactive() and facet_grid_interactive() that both work with labeller_interactive().
  • interactive guide functions: guide_colorbar_interactive(), guide_colourbar_interactive(), guide_legend_interactive().
  • interactive theme elements: element_line_interactive(), element_rect_interactive(), element_text_interactive(), label_interactive.

These understand three main aesthetics to let you add interactivity:

  • tooltip: column of dataset that contains tooltips to be displayed when mouse is over elements.
  • data_id: column of dataset that contains id to be associated with elements. This aesthetic is mandatory when you want to use an hover effect or when you want to enable selection of points in shiny applications.
  • onclick: column of dataset that contains javascript function to be executed when elements are clicked.

Let’s prepare a ggplot object with the mpg dataset.

library(ggplot2)
library(ggiraph)
g <- ggplot(mpg, aes(x = displ, y = cty))

The first example shows how to add a tooltip:

my_gg <- g + 
  geom_point_interactive(aes(tooltip = model, data_id = model), 
    size = 3, hover_nearest = TRUE)
girafe(ggobj = my_gg)