unhcrthemes

Parameters of theme_unhcr

The theme_unhcr function comes with various parameters to customize your plot:

• font_family: Sets the base font family, default is “Lato”.
• font_size: The base font size in points, default is 12.
• plot_title_size: Adjusts the plot title size relative to the base font size.
• plot_title_margin: Sets the bottom margin of the plot title.
• subtitle_size: Sets the font size for subtitles.
• subtitle_margin: Sets the bottom margin for subtitles.
• strip_text_size: Adjusts the facet label font size.
• strip_text_face: Sets the font face for facet labels, default is “bold”.
• strip_text_just: Determines the justification for facet labels.
• caption_size: Sets the font size for captions.
• caption_margin: Sets the top margin for captions.
• axis_text: Toggles the axis text on or off.
• axis_text_size: Sets the font size for axis text.
• axis_title: Toggles the axis title on or off.
• axis_title_size: Sets the font size for axis titles.
• axis: Toggles the axis on or off.
• axis_ticks: Toggles the axis ticks on or off.
• grid: Controls the display of grid lines.
• legend: Toggles the legend on or off.
• legend_text_size: Sets the font size for legend text.
• legend_title: Toggles the legend title on or off.
• legend_title_size: Sets the font size for legend titles.
• plot_margin: Sets the margin around the plot.
• plot_background: Sets the background color of the plot.
• void: If TRUE, removes all grid lines, ticks, and axes.

Usage

After loading the {unhcrthemes} package, you can apply the theme to any {ggplot2} chart, by simply adding theme_unhcr at your call. For example:

# Load packages
library(ggplot2)
library(unhcrthemes)

# Create some data
df <- data.frame(
  date = factor(rep(2010:2020, 2)),
  val = c(
    10.2, 10.2, 10.2, 11.5, 14,
    15.8, 17, 19.5, 20.5, 24.5, 20.6,
    4.9, 4.9, 4.9, 5.5, 5.5, 5.6,
    5.6, 5.7, 5.7, 5.8, 5.9
  ),
  set = rep(c("Set 1", "Set 2"), each = 11)
)

# Base plot with theme_unhcr()
ggplot(
  data = df,
  aes(x = date, y = val, fill = set)
) +
  geom_col(
    position = position_stack(reverse = TRUE),
    width = 0.8
  ) +
  labs(
    title = "My title | 2010-2020",
    subtitle = "My subtitle",
    x = "date",
    y = "values",
    caption = "Source: UNHCR, the UN Refugee Agency"
  ) +
  theme_unhcr()

The theme comes with some default settings, but you can customize most of it by adding parameters to the function call, as we will explore below.

Grid

The grid parameter controls the display of both major and minor grid lines in your plot. By default, major grid lines are visible and minor ones are hidden.

Using grid = "XY" adds both major X and Y grid lines, grid = "X" adds only major X grid lines, grid = "Y" adds only major Y grid lines, and grid = FALSE removes all grid lines. You can add minor grid lines by using lowercase "xy", "x" or "y". For example, let’s keep only the major Y grid lines:

ggplot(
  data = df,
  aes(x = date, y = val, fill = set)
) +
  geom_col(
    position = position_stack(reverse = TRUE),
    width = 0.8
  ) +
  labs(
    title = "My title | 2010-2020",
    subtitle = "My subtitle",
    x = "date",
    y = "values",
    caption = "Source: UNHCR, the UN Refugee Agency"
  ) +
  theme_unhcr(
    grid = "Y" # Only major Y grid lines
  )

Axis

Unsurprisingly, the axis represents the axis lines. However, it also includes different axis elements such as the axis title, axis text, and axis ticks.

ggplot(
  data = df,
  aes(x = date, y = val, fill = set)
) +
  geom_col(
    position = position_stack(reverse = TRUE),
    width = 0.8
  ) +
  labs(
    title = "My title | 2010-2020",
    subtitle = "My subtitle",
    x = "date",
    y = "values",
    caption = "Source: UNHCR, the UN Refugee Agency"
  ) +
  theme_unhcr(
    grid = "Y",
    axis = "X" # Only X axis
  )

ggplot(
  data = df,
  aes(x = date, y = val, fill = set)
) +
  geom_col(
    position = position_stack(reverse = TRUE),
    width = 0.8
  ) +
  labs(
    title = "My title | 2010-2020",
    subtitle = "My subtitle",
    x = "date",
    y = "values",
    caption = "Source: UNHCR, the UN Refugee Agency"
  ) +
  scale_y_continuous(
    expand = expansion(c(0, 0.01)) # Remove axis expansion
  ) +
  theme_unhcr(
    grid = "Y",
    axis = "X"
  )

ggplot(
  data = df,
  aes(x = date, y = val, fill = set)
) +
  geom_col(
    position = position_stack(reverse = TRUE),
    width = 0.8
  ) +
  labs(
    title = "My title | 2010-2020",
    subtitle = "My subtitle",
    y = "values",
    caption = "Source: UNHCR, the UN Refugee Agency"
  ) +
  scale_y_continuous(
    expand = expansion(c(0, 0.01))
  ) +
  theme_unhcr(
    grid = "Y",
    axis = "X",
    axis_title = "Y" # Only Y axis title
  )

Text

Like all the chart elements, the different text elements, such as the plot title, subtitle, caption, and more, can be controlled using the theme_unhcr function. We encourage you, not to touch any of these parameters, as they are part of the UNHCR branding and should be used as is. However, you can still adjust the font size, font family, margin or justification of each of these elements using, for example, the plot_title_size, plot_title_margin, etc. parameters.

On top of the theme_unhcr parameters, the {unhcrthemes} package natively incorporates the {ggtext} package for advanced text rendering in the title, subtitle and caption components. To showcase this, you can use the {ggtext} functionalities to include styled text directly in your plots.

ggplot(
  data = df,
  aes(x = date, y = val, fill = set)
) +
  geom_col(
    position = position_stack(reverse = TRUE),
    width = 0.8
  ) +
  labs(
    # Add some HTML style to the title
    title = "My title including <span style='color:#0072BC;'>highlight color</span> | 2010-2020",
    # Automatic wrapping of long text
    subtitle = "My really long subtitle that will cover more than one line and that will be automatically wrapped thanks to ggtext so I don't have to manually put a line break",
    y = "values",
    # Line break in the caption, use <br> instead of \n
    caption = "Note: As it's HTML text the line break symbol is not '\\n'<br>Source: UNHCR, the UN Refugee Agency"
  ) +
  scale_y_continuous(
    expand = expansion(c(0, 0.01))
  ) +
  theme_unhcr(
    grid = "Y",
    axis = "X",
    axis_title = "Y"
  )

ggplot(
  data = df,
  aes(x = date, y = val, fill = set)
) +
  geom_col(
    position = position_stack(reverse = TRUE),
    width = 0.8
  ) +
  # Add geom_text
  geom_text(aes(label = scales::number_format(accuracy = 0.1)(val)),
    position = position_stack(vjust = 0.5, reverse = TRUE),
    show.legend = FALSE
  ) +
  labs(
    title = "My title including <span style='color:#0072BC;'>highlight color</span> | 2010-2020",
    subtitle = "My really subtitle that will cover more than one line and that will be automatically wrapped thanks to ggtext so I don't have to manually put a line break",
    y = "values",
    caption = "Note: As it's HTML text the line break symbol is not '\\n'<br>Source: UNHCR, the UN Refugee Agency"
  ) +
  scale_y_continuous(
    expand = expansion(c(0, 0.01))
  ) +
  theme_unhcr(
    grid = "Y",
    axis = "X",
    axis_title = "Y"
  )

Color palettes

The {unhcrthemes} package also comes with the UNHCR color palettes, which can be used in your plots. Use the display_unhcr_all() function to show all the available palettes. These palettes can be used directly in your plots using the scale functions. For example, let’s use the default palette in the scale_fill_unhcr_d() function:

ggplot(
  data = df,
  aes(x = date, y = val, fill = set)
) +
  geom_col(
    position = position_stack(reverse = TRUE),
    width = 0.8
  ) +
  labs(
    title = "My title including <span style='color:#0072BC;'>highlight color</span> | 2010-2020",
    subtitle = "My really subtitle that will cover more than one line and that will be automatically wrapped thanks to ggtext so I don't have to manually put a line break",
    y = "values",
    caption = "Note: As it's HTML text the line break symbol is not '\\n'<br>Source: UNHCR, the UN Refugee Agency"
  ) +
  scale_y_continuous(
    expand = expansion(c(0, 0.01))
  ) +
  scale_fill_unhcr_d() +
  theme_unhcr(
    grid = "Y",
    axis = "X",
    axis_title = "Y"
  )

Void

To simplify the creation of pie/donut charts or maps, the theme_unhcr function comes with a void parameter. When set to TRUE, this parameter removes all grid lines, ticks, and axes. For example, let’s create a pie chart:

ggplot(
  data = dplyr::filter(df, date == 2020),
  aes(x = date, y = val, fill = set)
) +
  geom_col(
    position = position_stack(reverse = TRUE),
    width = 0.8
  ) +
  labs(
    title = "My title | 2020",
    subtitle = "My subtitle",
    y = "values",
    caption = "Source: UNHCR, the UN Refugee Agency"
  ) +
  scale_fill_unhcr_d() +
  coord_polar(
    theta = "y",
    direction = -1
  ) +
  theme_unhcr(
    void = TRUE # Remove all grid lines, ticks, and axes
  )

Conclusion

With {unhcrthemes}, creating UNHCR-compliant visualizations in R is straightforward, providing a consistent and branded look for your graphics.

For more information on each parameter and usage, visit the function documentation page and the UNHCR Data Visualization Platform