geom_fit_text() shrinks, grows or wraps text to fit inside a defined rectangular area.

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(0.1, "lines"), place = "centre",
  min.size = 4, grow = FALSE, reflow = FALSE,
  width = grid::unit(40, "mm"), height = grid::unit(40, "mm"),
  formatter = NULL, ...)

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

Amount of horizontal and vertical padding around the text, expressed as grid::unit() objects. Default to 1 mm and 0.1 lines respectively.

place

Where inside the box to place the text. Default is 'centre'; other options are 'topleft', 'top', 'topright', etc.

min.size

Minimum font size, in points. If provided, text that would need to be shrunk below this size to fit the box will not be drawn. Defaults to 4 pt.

grow

If TRUE, text will be grown as well as shrunk to fill the box. See Details.

reflow

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

width, height

When using x and/or y aesthetics, these will be used to determine the width and/or height of the box. These should be either numeric values on the x and y scales or grid::unit() objects. Both default to 40 mm units.

formatter

A function that will be applied to the text before it is drawn. This can be useful when using geom_fit_text() in an automated context, 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.

Details

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

In addition to the normal geom_text() aesthetics, geom_fit_text() requires you to specify the box in which you wish to fit the text, usually with 'xmin', 'xmax', 'ymin' and 'ymax' aesthetics. Alternatively, you can specify the centre of the box with 'x' and/or 'y', and the height and/or width of the box with 'height' and/or 'width' arguments. This can be useful when one or both axes are discrete. 'height' and 'width' should be provided as grid::unit() objects, and both default to 40 mm.

By default, the text will be drawn as if with geom_text(), unless it is too big for the box, in which case 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. When grow = FALSE (default), text that fits the box will be drawn as if with geom_text(); text that doesn't fit the box will be reflowed until it does. If the text cannot be made to fit by reflowing alone, it will be reflowed to match the aspect ratio of the box as closely as possible, then be shrunk to fit the box. When grow = TRUE, the text will be reflowed to best match the aspect ratio of the box, then made to fill the box completely whether that requires growing or shrinking. Existing line breaks in the text will be respected when reflowing.

Aesthetics

  • label (required)

  • xmin, xmax OR x (required)

  • ymin, ymax OR y (required)

  • alpha

  • angle

  • colour

  • family

  • fontface

  • lineheight

  • size

Examples

ggplot2::ggplot(ggplot2::presidential, ggplot2::aes(ymin = start, ymax = end, label = name, fill = party, xmin = 0, xmax = 1)) + ggplot2::geom_rect(colour = 'black') + geom_fit_text(grow = TRUE)