Skip to contents

A 'ggplot2' geom to fit text inside a box

Source: R/geom_bar_text.R, R/geom_fit_text.R
geom_fit_text.Rd

geom_fit_text() shrinks, grows and wraps text to fit inside a defined box. geom_bar_text() is a convenience wrapper around geom_fit_text() for labelling bar plots generated with geom_col() and geom_bar().

Usage

geom_bar_text(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  padding.x = grid::unit(1, "mm"),
  padding.y = grid::unit(1, "mm"),
  min.size = 8,
  place = NULL,
  outside = NULL,
  grow = FALSE,
  reflow = FALSE,
  hjust = NULL,
  vjust = NULL,
  fullheight = NULL,
  width = NULL,
  height = NULL,
  formatter = NULL,
  contrast = NULL,
  rich = FALSE,
  ...
)

geom_fit_text(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  padding.x = grid::unit(1, "mm"),
  padding.y = grid::unit(1, "mm"),
  min.size = 4,
  place = "centre",
  outside = FALSE,
  grow = FALSE,
  reflow = FALSE,
  hjust = NULL,
  vjust = NULL,
  fullheight = NULL,
  width = NULL,
  height = NULL,
  formatter = NULL,
  contrast = FALSE,
  flip = FALSE,
  rich = FALSE,
  ...
)

Arguments

mapping

ggplot2::aes() object as standard in 'ggplot2'. Note that aesthetics specifying the box must be provided. See Details.

data, stat, position, na.rm, show.legend, inherit.aes, ...

Standard geom arguments as for ggplot2::geom_text().

padding.x, padding.y

Horizontal and vertical padding around the text, expressed in grid::unit() objects. Both default to 1 mm.

min.size

Minimum font size, in points. Text smaller than this, whether as supplied or after being shrunk to fit the box, will be hidden. Defaults to 4 pt (8 pt for geom_bar_text()).

place

Where inside the box to place the text. Default is 'centre'; other options are 'topleft', 'top', 'topright', 'right', 'bottomright', 'bottom', 'bottomleft', 'left', and 'center'/'middle' which are both synonyms for 'centre'. For geom_bar_text(), will be set heuristically if not specified.

outside

If TRUE, text placed in one of 'top', 'right', 'bottom' or 'left' that would need to be shrunk smaller than min.size to fit the box will be drawn outside the box if possible. This is mostly useful for drawing text inside bar/column geoms. Defaults to TRUE for position = "identity" when using geom_bar_text(), otherwise FALSE.

grow

If TRUE, text will be grown as well as shrunk to fill the box. Defaults to FALSE.

reflow

If TRUE, text will be reflowed (wrapped) to better fit the box. Defaults to FALSE.

hjust, vjust

Horizontal and vertical justification of the text. vjust defaults to 0.5. hjust defaults to 0.5, except for left placements ('left', 'topleft' and 'bottomleft'), where it defaults to 0, and right placements, where it defaults to 1.

fullheight

If TRUE, descenders will be counted when resizing and placing text; if FALSE, only the x-height and ascenders will be counted. The main use for this option is for aligning text at the baseline (FALSE) or preventing descenders from spilling outside the box (TRUE). By default this is set automatically depending on grow.

width, height

When using x and/or y aesthetics, these set the width and/or height of the box. These should be either grid::unit() objects or numeric values on the x and y scales.

formatter

A function that will be applied to the text before it is drawn. This is useful when using geom_fit_text() in contexts involving interpolated variables, such as with the 'gganimate' package. formatter will be applied serially to each element in the label column, so it does not need to be a vectorised function.

contrast

If TRUE and in combination with a fill aesthetic, the colour of the text will be inverted for better contrast against dark background fills. FALSE by default for geom_fit_text(), set heuristically for geom_bar_text().

rich

If TRUE, text will be formatted with markdown and HTML markup as implemented by gridtext::richtext_grob(). FALSE by default. Rich text cannot be drawn in polar coordinates. Please note that rich text support is experimental and breaking changes are likely.

flip

If TRUE, when in polar coordinates 'upside-down' text will be flipped the 'right way up', to enhance readability.

Details

Except where noted, geom_fit_text() behaves more or less like ggplot2::geom_text().

There are three ways to define the box in which you want the text to be drawn. The extents of the box on the x and y axes are independent, so any combination of these methods can be used:

  1. If the x and/or y aesthetics are used to set the location of the box, the width and/or height will be set automatically based on the spacing between values on the axis, following the method used by ggplot2::geom_boxplot().

  2. Alternatively, if x and/or y aesthetics are used, the width and/or height of the box can be overridden with a 'width' and/or 'height' argument. These should be grid::unit() objects; if not, they will be assumed to use the native axis scale.

  3. The boundaries of the box can be set using the aesthetics 'xmin' and 'xmax', and/or 'ymin' and 'ymax'.

If the text is too big for the box, it will be shrunk to fit the box. With grow = TRUE, the text will be made to fill the box completely whether that requires shrinking or growing.

reflow = TRUE will cause the text to be reflowed (wrapped) to better fit in the box. If the text cannot be made to fit by reflowing alone, it will be reflowed then shrunk to fit the box. Existing line breaks in the text will be respected when reflowing.

geom_fit_text() includes experimental support for drawing text in polar coordinates (by adding coord_polar() to the plot), however not all features are available when doing so.

Aesthetics

  • label (required)

  • (xmin AND xmax) OR x (required)

  • (ymin AND ymax) OR y (required)

  • alpha

  • angle

  • colour

  • family

  • fill (with contrast = TRUE, used to select a contrasting text colour)

  • fontface

  • lineheight

  • size (in points; note that this differs from ggplot2::geom_text(), which expresses size in mm)

geom_bar_text() requires only the x and y aesthetics, which are used to infer the extent of the bar. If no label aesthetic is provided, the bar's value (y, or x for flipped bars) will be used as the label.

Examples


ggplot2::ggplot(ggplot2::presidential, ggplot2::aes(ymin = start, ymax = end,
    label = name, x = party)) +
  geom_fit_text(grow = TRUE)