ggrepel examples

Kamil Slowikowski



ggrepel provides geoms for ggplot2 to repel overlapping text labels:

  • geom_text_repel()
  • geom_label_repel()

Text labels repel away from each other, away from data points, and away from edges of the plotting area.

Let’s compare geom_text() and geom_text_repel():

plot of chunk comparison


Options available for geom_text() and geom_label() are also available for geom_text_repel() and geom_label_repel(), including size, angle, family, fontface, etc.

ggrepel provides additional options for geom_text_repel and geom_label_repel:

Option Default Description
force 1 force of repulsion between overlapping text labels
direction "both" move text labels “both” (default), “x”, or “y” directions
max.iter 2000 maximum number of iterations to try to resolve overlaps
nudge_x 0 adjust the starting x position of the text label
nudge_y 0 adjust the starting y position of the text label
box.padding 0.25 lines padding around the text label
point.padding 0 lines padding around the labeled data point
segment.color "black" line segment color
segment.size 0.5 mm line segment thickness
segment.alpha 1.0 line segment transparency
arrow NULL render line segment as an arrow with grid::arrow()


Do not repel labels from data points

Set point.padding = NA to prevent label repulsion away from data points.

Now labels move away from each other and away from the edges of the plot.

plot of chunk point_padding_na

Limit labels to a specific area

Use options xlim and ylim to constrain the labels to a specific area. Limits are specified in data coordinates. Use NA when there is no lower or upper bound in a particular direction.

Here we also use grid::arrow() to render the segments as arrows.

plot of chunk xlim

Align labels on the top or bottom edge

Use hjust or vjust to justify the text neatly:

  • hjust = 0 for left-align
  • hjust = 0.5 for center
  • hjust = 1 for right-align

Sometimes the labels do not align perfectly. Try using direction = "x" to limit label movement to the x-axis (left and right) or direction = "y" to limit movement to the y-axis (up and down). The default is direction = "both".

Also try using xlim() and ylim() to increase the size of the plotting area so all of the labels fit comfortably.

plot of chunk direction_x

Align text vertically with nudge_y and allow the labels to move horizontally with direction = "x":

plot of chunk neat-offset-x

Align labels on the left or right edge

Set direction to “y” and try hjust 0.5, 0, and 1:

plot of chunk direction_y

Align text horizontally with nudge_x and hjust, and allow the labels to move vertically with direction = "y":

plot of chunk neat-offset-y

Source code

View the source code for this vignette on GitHub.

R Session Info

## R version 3.5.0 (2018-04-23)
## Platform: x86_64-apple-darwin17.4.0 (64-bit)
## Running under: macOS High Sierra 10.13.3
## Matrix products: default
## BLAS/LAPACK: /usr/local/Cellar/openblas/0.2.20_2/lib/libopenblasp-r0.2.20.dylib
## locale:
## [1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## other attached packages:
## [1] ggrepel_0.8.0      ggplot2_2.2.1.9000 gridExtra_2.3     
## [4] knitr_1.20        
## loaded via a namespace (and not attached):
##  [1] Rcpp_0.12.16      codetools_0.2-15  digest_0.6.15    
##  [4] withr_2.1.2       grid_3.5.0        plyr_1.8.4       
##  [7] gtable_0.2.0      magrittr_1.5      evaluate_0.10.1  
## [10] scales_0.5.0.9000 highr_0.6         pillar_1.2.2     
## [13] rlang_0.2.0.9001  stringi_1.1.7     lazyeval_0.2.1   
## [16] labeling_0.3      tools_3.5.0       stringr_1.3.0    
## [19] munsell_0.4.3     compiler_3.5.0    colorspace_1.3-2 
## [22] tibble_1.4.2