Repository files navigation

ggfittext is a ggplot2 extension for fitting text into boxes.

Install the release version of ggfittext from CRAN:

install.packages("ggfittext")

If you want the development version, install it from GitHub:

devtools::install_github("wilkox/ggfittext")

Sometimes you want to draw some text in a ggplot2 plot so that it fitsinside a defined area. You can do this by manually fiddling with thefont size, but this is tedious and un-reproducible. ggfittext provides ageom calledgeom_fit_text() that automatically resizes text to fitinside a box. It works like this:

ggplot(animals, aes(x=type,y=flies,label=animal))+  geom_tile(fill="white",colour="black")+  geom_fit_text()

As withgeom_text(), the position of the text is set by thex andy aesthetics.geom_fit_text() tries to infer the width and height ofthe box in which the text is allowed to fit, and shrinks down any textthat is too big.

Another way to make the text fit in the box is by reflowing it; that is,wrapping it over multiple lines. With thereflow = TRUE argument,geom_fit_text() will reflow the text before (if still necessary)shrinking it:

ggplot(animals, aes(x=type,y=flies,label=animal))+  geom_tile(fill="white",colour="black")+  geom_fit_text(reflow=TRUE)

If you want the text to be as large as possible, the argumentgrow = TRUE will increase the text size to the maximum that will fitin the box. This works well in conjunction withreflow:

ggplot(animals, aes(x=type,y=flies,label=animal))+  geom_tile(fill="white",colour="black")+  geom_fit_text(reflow=TRUE,grow=TRUE)

By default, text is placed in the centre of the box. However, you canplace it in a corner or on a side of the box with theplace argument,which takes values like “top”, “topright”, “bottomleft” and so on:

ggplot(animals, aes(x=type,y=flies,label=animal))+  geom_tile(fill="white",colour="black")+  geom_fit_text(place="topleft",reflow=TRUE)

ggfittext also provides a geomgeom_bar_text() for labelling bars inbar plots:

ggplot(altitudes, aes(x=craft,y=altitude,label=altitude))+  geom_col()+  geom_bar_text()

geom_bar_text() works with stacked bar plots:

ggplot(beverages, aes(x=beverage,y=proportion,label=ingredient,fill=ingredient))+  geom_col(position="stack")+  geom_bar_text(position="stack",reflow=TRUE)

And it works with dodged bar plots, and with flipped bar plots:

ggplot(beverages, aes(x=beverage,y=proportion,label=ingredient,fill=ingredient))+  geom_col(position="dodge")+  geom_bar_text(position="dodge",grow=TRUE,reflow=TRUE,place="left")+  coord_flip()

With therich = TRUE argument,geom_fit_text() andgeom_bar_text()both support a limited subset of Markdown and HTML markup for text(rendered withgridtext).

ggplot(animals_rich, aes(x=type,y=flies,label=animal))+  geom_tile(fill="white",colour="black")+  geom_fit_text(reflow=TRUE,grow=TRUE,rich=TRUE)

Rich text cannot be drawn in polar coordinates. Please note that thisfeature is liable to change, and is subject to upstream changes togridtext.

If you want to manually set the limits of the box (instead of havingthem inferred fromx andy), you can usexmin &xmax and/orymin &ymax:

ggplot(presidential, aes(ymin=start,ymax=end,x=party,label=name))+  geom_fit_text(grow=TRUE)+  geom_errorbar(alpha=0.5)

Alternatively, you can set the width and/or height with thewidthand/orheight arguments, which should begrid::unit() objects. Thehorizontal and/or vertical centre of the box will be defined byxand/ory.

Text can be drawn in polar coordinates withgeom_fit_text() simply byaddingcoord_polar() to the plot. This feature is experimental and anybug reports are very welcome.

p<- ggplot(gold, aes(xmin=xmin,xmax=xmax,ymin=ymin,ymax=ymax,fill=linenumber,label=line))+  coord_polar()+  geom_rect()+  scale_fill_gradient(low="#fee391",high="#238443")p+ geom_fit_text(min.size=0,grow=TRUE)

When text is drawn in polar coordinates, theflip = TRUE argument canbe used to flip upside-down text the ‘right way up’ to ease readability:

p+ geom_fit_text(min.size=0,grow=TRUE,flip=TRUE)

All arguments togeom_fit_text() can also be used withgeom_bar_text().

• contrast can be used to automatically invert the colour of thetext so it contrasts against a backgroundfill:

ggplot(animals, aes(x=type,y=flies,fill=mass,label=animal))+  geom_tile()+  geom_fit_text(reflow=TRUE,grow=TRUE,contrast=TRUE)

• padding.x andpadding.y can be used to set the paddingbetween the text and the edge of the box. By default this is 1 mm.These values must be given asgrid::unit() objects.
• min.size sets the minimum font size in points, by default 4pt. Text smaller than this will be hidden (see alsooutside).
• outside isFALSE by default forgeom_fit_text(). IfTRUE,text that is placed at “top”, “bottom”, “left” or “right” and must beshrunk smaller thanmin.size to fit in the box will be flipped tothe outside of the box (if it fits there). This is mostly useful fordrawing text inside bars in a bar plot.
• hjust andvjust set the horizontal and verticaljustification of the text, scaled between 0 (left/bottom) and 1(right/top). These are both 0.5 by default.
• formatter allows you to provide a function that will be appliedto the text before it is drawn. This is mostly useful in contextswhere variables may be interpolated, such as when usinggganimate.
• fullheight is automatically set depending on place, but can beoverridden with this option. This is used to determine the boundingbox around the text. IfFALSE, the bounding box includes thex-height of the text and ascenders, but not any descenders. If TRUE,it extends from the top of the ascenders to the bottom of thedescenders. This is mostly useful in situations where you want toensure the baseline of text is consistent between labels(fullheight = FALSE), or when you want to avoid descenders spillingout of the bounding box (fullheight = TRUE).