Skip to contents

Create a girafe object

Source: R/girafe.R
girafe.Rd

Create an interactive graphic with a ggplot object to be used in a web browser.

Usage

girafe(
  code,
  ggobj = NULL,
  pointsize = 12,
  width_svg = NULL,
  height_svg = NULL,
  options = list(),
  dependencies = NULL,
  check_fonts_registered = FALSE,
  check_fonts_dependencies = FALSE,
  ...
)

Arguments

code

Plotting code to execute

ggobj

ggplot object to print. Argument code will be ignored if this argument is supplied.

pointsize

the default pointsize of plotted text in pixels, default to 12.

width_svg, height_svg

The width and height of the graphics region in inches. The default values are 6 and 5 inches. This will define the aspect ratio of the graphic as it will be used to define viewbox attribute of the SVG result.

If you use girafe() in an 'R Markdown' document, we recommend not using these arguments so that the knitr options fig.width and fig.height are used instead.

options

a list of options for girafe rendering, see opts_tooltip(), opts_hover(), opts_selection(), ...

dependencies

Additional widget HTML dependencies, see htmlwidgets::createWidget().

check_fonts_registered

whether to check if fonts families found in the ggplot are registered with 'systemfonts'.

check_fonts_dependencies

whether to check if fonts families found in the ggplot are found in the dependencies list.

...

arguments passed on to dsvg()

Details

Use geom_zzz_interactive to create interactive graphical elements.

Tooltips can be displayed when mouse is over graphical elements.

If id are associated with points, they get animated when mouse is over and can be selected when used in shiny apps.

On click actions can be set with javascript instructions. This option should not be used simultaneously with selections in Shiny applications as both features are "on click" features.

When a zoom effect is set, "zoom activate", "zoom desactivate" and "zoom init" buttons are available in a toolbar.

When selection type is set to 'multiple' (in Shiny applications), lasso selection and lasso anti-selections buttons are available in a toolbar.

Managing Grouping with Interactive Aesthetics

Adding an interactive aesthetic like tooltip can sometimes alter the implicit grouping that ggplot2 performs automatically.

In these cases, you must explicitly specify the group aesthetic to ensure correct graph rendering by clearly defining the variables that determine the grouping.

mapping = ggplot2::aes(tooltip = .data_tooltip, group = interaction(factor1, factor2, ...))

This precaution is necessary:

  • ggplot2 automatically determines grouping based on the provided aesthetics

  • Interactive aesthetics added by ggiraph can interfere with this logic

  • Explicit group specification prevents unexpected behavior and ensures predictable results

Widget options

girafe animations can be customized with function girafe_options(). Options are available to customize tooltips, hover effects, zoom effects selection effects and toolbar.

Widget sizing

girafe graphics are responsive, which mean, they will be resized according to their container. There are two responsive behavior implementations:

  • one for Shiny applications and flexdashboard documents,

  • and another one for other documents (i.e. R markdown and saveWidget).

Graphics are created by an R graphic device (i.e pdf, png, svg here) and need arguments width and height to define a graphic region. Arguments width_svg and height_svg are used as corresponding values. They are defining the aspect ratio of the graphic. This proportion is always respected when the graph is displayed.

When a girafe graphic is in a Shiny application, graphic will be resized according to the arguments width and height of the function girafeOutput. Default values are '100\ outer bounding box of the graphic (the HTML element that will contain the graphic with an aspect ratio).

When a girafe graphic is in an R markdown document (producing an HTML document), the graphic will be resized according to the argument width of the function girafe. Its value is beeing used to define a relative width of the graphic within its HTML container. Its height is automatically adjusted regarding to the argument width and the aspect ratio.

See also

girafe_options(), validated_fonts(), dsvg()

Examples

library(ggplot2)
library(ggiraph)
library(gdtools)

register_liberationsans()
#> [1] TRUE

dataset <- mtcars
dataset$carname <- row.names(mtcars)

gg_point <- ggplot(
  data = dataset,
  mapping = aes(
    x = wt, y = qsec, color = disp,
    tooltip = carname, data_id = carname
  )
) +
  geom_point_interactive(hover_nearest = TRUE, size = 11/.pt) +
  theme_minimal(base_family = "Liberation Sans", base_size = 11)

x <- girafe(
  ggobj = gg_point,
  dependencies = list(
    liberationsansHtmlDependency()
  )
)

x