Skip to contents

ggpattern

ggpattern provides custom ggplot2 geoms which support filled areas with geometric and image-based patterns.

Reading the articles/vignettes on the package website is probably the best way to get started.

Feature Summary

  • Custom versions of (almost) all the geoms from ggplot2 which have a region which can be filled.
  • A suite of aesthetics for controlling the pattern appearance (e.g. pattern_alpha)
  • The ability to include user-defined patterns

Installation

You can install the development version from R-universe

install.packages('ggpattern', repos = c('https://trevorld.r-universe.dev', 'https://cloud.r-project.org'))

or straight from the source hosted on Github using the remotes package:

# install.packages("remotes")
remotes::install_github("trevorld/ggpattern")

You can install the CRAN release version using:

install.packages("ggpattern")

Do note though that due to CRAN size limitations the CRAN version omits several vignettes that are contained in the development version (as well as on the package website).

Depending on your operating system, which dependencies you have not previously installed, and the method you choose to install ggpattern it is possible that you may need to first install some system libraries manually using a tool like apt, brew, dnf, etc. In particular as of June 2025 ggpattern depends on gridpattern which depends on sf which depends on s2 and units which may need you to install the system development libraries for Abseil, OpenSSL, and udunits2. If you pay close attention to any install.packages() error messages it will often tell you the name of the missing system library you need to install with apt, brew, dnf, etc. Alternative R package installers like {pak} or r2u may also be able to help install such system library dependencies if necessary.

An installation error is highly unlikely to be an issue with ggpattern itself. Please don’t open a Github issue unless you are sure it is an issue with ggpattern itself. If you have an error installing the package we strongly suggest that you look at all your error messages more closely to figure out which package dependency is failing to install and why. If necessary look up that package’s documentation for additional information in installing it. See https://thomasadventure.blog/posts/install-r-packages/ for more info on installing R packages.

Quickstart

  1. Take an existing plot which contains a geom with a fillable area e.g geom_col().
  2. Use the ggpattern version of the geom e.g. ggpattern::geom_col_pattern() instead of ggplot2::geom_col()
  3. Set the aesthetic pattern to your choice of pattern e.g pattern = 'stripe', and set other options using pattern_* aesthetics
df <- data.frame(level = c("a", "b", "c", 'd'), outcome = c(2.3, 1.9, 3.2, 1))

ggplot(df) +
  geom_col_pattern(
    aes(level, outcome, pattern_fill = level), 
    pattern = 'stripe',
    fill    = 'white',
    colour  = 'black'
  ) +
  theme_bw(18) +
  theme(legend.position = 'none') + 
  labs(
    title    = "ggpattern::geom_col_pattern()",
    subtitle = "pattern = 'stripe'"
  ) +
  coord_fixed(ratio = 1/2)

A bar chart with striped bars

Gallery

Example of bar chart filled with the 'kitten' 'placeholder' pattern Example of bar chart filled with black and white 'geometry' patterns Example of a bar chart filled with colored 'geometry' patterns A horizontal bar charts with flag images at the end of each bar A density chart filled with 'image' patterns A density chart filled with 'geometry' patterns A map filled with greyscale 'magick' patterns Rectangles filled with gradients

Feature Details

Available Geoms

ggpattern includes versions of (nearly) all geoms from ggplot2 which could plausibly support being filled with a pattern.

See the vignette galleries for examples of all the available geoms filled with geometry-based patterns and image-based/array-based patterns.

Click to show/hide list of supported geoms

ggplot2 ggpattern
geom_area geom_area_pattern
geom_bar geom_bar_pattern
geom_bin2d geom_bin2d_pattern
geom_boxplot geom_boxplot_pattern
geom_col geom_col_pattern
geom_crossbar geom_crossbar_pattern
geom_density geom_density_pattern
geom_histogram geom_histogram_pattern
geom_map geom_map_pattern
geom_polygon geom_polygon_pattern
geom_rect geom_rect_pattern
geom_ribbon geom_ribbon_pattern
geom_sf geom_sf_pattern
geom_tile geom_tile_pattern
geom_violin geom_violin_pattern

New aesthetics

To control pattern appearance, a raft of new aesthetics have been added. e.g.  pattern_alpha, pattern_filename, pattern_density.

There are also scale functions to control each of these new aesthetics e.g.  scale_pattern_alpha_discrete.

Not all aesthetics apply to all patterns. See the individual pattern vignettes for which aesthetics it uses, or see the first vignette on developing user-defined patterns for a table of aesthetic use by pattern, or see the individual vignettes for each pattern.

A default of “pattern (x)” means the aesthetic is unset by default (internally NaN) so the pattern’s own default applies, which for most patterns is gridpattern’s generic default x (see the documentation of the corresponding gridpattern::grid.pattern_<name>() function).

Click to show/hide list of new aesthetics

aesthetic description default possible values
pattern Name of the pattern to draw ‘stripe’ stripe, crosshatch, circle, image, placeholder, magick, gradient, plasma
pattern_type Generic control option pattern (NA) pattern-dependent
pattern_subtype Generic control option pattern (NA) pattern-dependent
pattern_alpha Alpha pattern (NA) value in range [0, 1] (npc units)
pattern_linetype Stroke linetype pattern (1) linetype
pattern_size Stroke linewidth pattern (0.5) linewidth
pattern_shape Plotting shape pattern (1) shapes
pattern_colour Stroke colour pattern (‘grey20’) colour
pattern_fill Fill colour pattern (‘grey80’) colour
pattern_fill2 Second fill colour pattern (‘#4169E1’) colour
pattern_angle Rotation angle pattern (30) angle in degrees
pattern_density Approx. fraction of area the pattern fills pattern (0.2) value in range [0, 1] (fraction)
pattern_spacing Spacing between repetitions of pattern pattern (0.05) value in range [0, 1] (npc units)
pattern_xoffset Shift pattern along x axis pattern (0) value in range [0, 1] (npc units)
pattern_yoffset Shift pattern along y axis pattern (0) value in range [0, 1] (npc units)
pattern_aspect_ratio Aspect ratio adjustment plot / key aspect ratio usual range [0.01, 10]
pattern_key_scale_factor Scale factor for pattern in legend 1
pattern_filename Image filename/URL pattern (’’) Filename/URL
pattern_gravity Image placement pattern (‘center’) magick::gravity_types()
pattern_filter Image scaling filter pattern (‘lanczos’) magick::filter_types()
pattern_scale Scale pattern (1) Multiplier
pattern_orientation Orientation pattern (‘vertical’) ‘vertical’, ‘horizontal’, ‘radial’
pattern_phase Phase pattern (0)
pattern_frequency Frequency pattern (0.1)
pattern_option_1 - 5 Generic options for expansion pattern (0)
pattern_grid Grid type pattern (‘square’) ‘square’, ‘hex’, ‘hex_circle’
pattern_res Pattern resolution (pixels per inch) ≈ device resolution Resolution
pattern_rot Shape rotation angle (within pattern) pattern (0) angle in degrees

User-Defined Patterns

Users can write their own pattern functions and ask ggpattern to use them, without having to include the pattern in the package. Register them with gridpattern::register_pattern().

See the vignette on developing patterns: vignette("developing-patterns", package = "ggpattern").

Vignettes

Note: due to CRAN package size limits many of these vignettes are only available in the Github version of ggpattern and the package website.

General examples

Exploration of pattern parameters and appearance

Developing your own pattern

Other examples

Limitations

  • Use pattern_aspect_ratio to override the internal aspect ratio calculation.
  • Legend rendering for patterns is still not great.
    • Use pattern_key_scale_factor to adjust legend appearance.
  • The Rstudio output device can be quite slow for plots with lots of patterns. It is often faster to save directly to PNG or PDF and view that.
  • Self intersecting geometry can be an issue.
  • Non-linear coordinate systems have not been tested.