Getting Started

Installation, setup, and your first CPAL visualization

Installation

From GitHub

cpaltemplates is hosted on GitHub and can be installed using remotes or devtools:

# Using remotes (recommended)
install.packages("remotes")
remotes::install_github("childpovertyactionlab/cpaltemplates")

# Or using devtools
install.packages("devtools")
devtools::install_github("childpovertyactionlab/cpaltemplates")

Dependencies

cpaltemplates requires R version 4.3.0 or higher. The package will automatically install required dependencies, but you may want to install suggested packages for full functionality:

# Core dependencies (installed automatically)
# fs, ggplot2, cli, yaml, gt, reactable, bslib, sass

# Suggested packages for extended features
install.packages(c(
  "highcharter",  # Interactive visualizations
  "mapgl",        # Interactive maps
  "cowplot",      # Logo placement
  "magick",       # Image processing for logos
  "showtext",     # Google Fonts for static plots
  "sysfonts",     # Font management
  "patchwork"     # Theme preview
))

Initial Setup

Loading the Package

library(cpaltemplates)

Font Setup

CPAL visualizations use Inter (primary) and Roboto (secondary) fonts from Google Fonts. Run this setup once per R session:

# Set up fonts for both static and interactive plots
setup_cpal_google_fonts()

Tip

Add setup_cpal_google_fonts() to your project’s setup script or .Rprofile to ensure fonts are always available.

Verifying Installation

Run these commands to verify everything is working:

# Check that colors load correctly
cpal_colors_primary()
#>   midnight       teal       pink     orange       gold
#>  "#004855"  "#007A8C"  "#C3257B"  "#ED683F"  "#AB8C01"

# Check that themes work
library(ggplot2)
p <- ggplot(mtcars, aes(wt, mpg)) +
  geom_point() +
  theme_cpal()
print(p)

# Check font availability
cpal_font_family()
#> [1] "Inter"  # or "Roboto" or "sans" if fonts unavailable

Understanding the Package Structure

cpaltemplates provides 81 functions organized into 9 categories. Each function is marked with a status indicator to help you understand its maturity level. Functions marked as “ready” are stable and recommended for use, while those “in development” are functional but may change, and those “under review” are being evaluated for updates or improvements.

✓ Ready to use ● In development ✗ Under review

Click each section below to see the available functions.

Color System (25 functions)

Status	Function	Description
✓	`cpal_colors()`	Get colors from any palette by name
✓	`cpal_colors_primary()`	Get primary brand colors
✓	`cpal_colors_extended()`	Get extended color set
✓	`cpal_color()`	Get a single color by name
✓	`cpal_get_color()`	Alias for getting single colors
✓	`cpal_get_primary_color()`	Get a primary color by name
✓	`cpal_palette()`	Generate a palette function
✓	`cpal_palettes()`	List all available palettes
✓	`cpal_palettes_categorical()`	Get categorical palettes
✓	`cpal_palettes_sequential()`	Get sequential palettes
✓	`cpal_palettes_diverging()`	Get diverging palettes
✓	`list_cpal_palettes()`	List palettes with metadata
✓	`quick_palette()`	Quick access to common palettes
✓	`view_cpal_palettes()`	Visual preview of palettes
✓	`cpal_color_ramp()`	Interpolate between colors
✓	`cpal_color_gradient()`	Create multi-color gradients
✓	`validate_color_contrast()`	Check WCAG contrast compliance
✓	`validate_brand_colors()`	Validate brand color usage
✓	`scale_color_cpal()`	ggplot2 color scale
✓	`scale_color_cpal_c()`	Continuous color scale
✓	`scale_color_cpal_d()`	Discrete color scale
✓	`scale_colour_cpal()`	Alias (British spelling)
✓	`scale_fill_cpal()`	ggplot2 fill scale
✓	`scale_fill_cpal_c()`	Continuous fill scale
✓	`scale_fill_cpal_d()`	Discrete fill scale

Theme System (11 functions)

Status	Function	Description
✓	`theme_cpal()`	Default CPAL theme
✓	`theme_cpal_minimal()`	Minimal/clean theme
✓	`theme_cpal_classic()`	Classic theme with axes
✓	`theme_cpal_dark()`	Dark background theme
✓	`theme_cpal_print()`	Print-optimized theme
✓	`theme_cpal_map()`	Theme for maps
✓	`theme_cpal_auto()`	Auto light/dark theme
✓	`theme_cpal_switch()`	Reactive theme switching
✓	`set_theme_cpal()`	Set default theme for session
✓	`make_theme_reactive()`	Create reactive theme for Shiny
✓	`preview_cpal_themes()`	Visual preview of all themes

Highcharter (18 functions)

Status	Function	Description
✓	`hc_theme_cpal_light()`	Light Highcharter theme
✓	`hc_theme_cpal_dark()`	Dark Highcharter theme
✓	`hc_theme_cpal_switch()`	Reactive theme for Shiny
✓	`hc_cpal_theme()`	Apply CPAL theme to chart
✓	`hc_colors_cpal()`	Set CPAL colors on chart
✓	`hc_tooltip_cpal()`	Styled tooltips
✓	`hc_yaxis_cpal()`	Formatted y-axis
✓	`hc_colorAxis_cpal()`	Color axis for heatmaps
✓	`hc_add_cpal_logo()`	Add logo to chart
✓	`hc_cpal_number_format()`	Number formatting options
✓	`hc_linetype_cpal()`	Line styling
✓	`hc_histogram_cpal()`	Histogram styling
✓	`hc_boxplot_style_cpal()`	Boxplot styling
✓	`hc_lollipop_cpal()`	Lollipop chart helper
✓	`hc_dumbbell_cpal()`	Dumbbell chart helper
✓	`hc_waterfall_colors_cpal()`	Waterfall chart colors
✓	`hc_treemap_style_cpal()`	Treemap styling
✓	`hc_treemap_data_cpal()`	Treemap data formatter

Tables (2 functions)

Status	Function	Description
✓	`cpal_table_gt()`	Styled GT table (static)
✓	`cpal_table_reactable()`	Styled Reactable (interactive)

Maps (5 functions)

Status	Function	Description
✓	`cpal_mapgl()`	Create styled mapgl map
✓	`add_cpal_popup_style()`	Apply CPAL styling to popup container
✓	`cpal_popup_html()`	Generate basic popup HTML content
✓	`cpal_popup_html_metrics()`	Generate popup HTML with metrics
✓	`cpal_legend_style()`	Get styled legend options for mapgl

Project Scaffolding (8 functions)

Status	Function	Description
✓	`start_project()`	Create new project from template
✗	`use_quarto_report()`	Add Quarto report template
✗	`use_quarto_slides()`	Add Quarto slides template
✗	`use_quarto_web()`	Add Quarto website template
✗	`use_shiny_app()`	Add Shiny app template
✗	`use_shiny_dashboard()`	Add Shiny dashboard template
✗	`use_shiny_theme()`	Add Shiny theme files
✗	`use_targets()`	Add targets pipeline

Brand & Assets (4 functions)

Status	Function	Description
✓	`use_cpal_brand()`	Add _brand.yml to project
✓	`validate_cpal_brand()`	Validate brand configuration
✓	`get_cpal_asset()`	Get path to package asset
✓	`update_cpal_assets()`	Update assets in project

Shiny & Dashboards (4 functions)

Status	Function	Description
✓	`cpal_dashboard_theme()`	bslib theme for dashboards
✓	`cpal_shiny()`	Initialize Shiny with CPAL theme
✓	`cpal_add_scss_enhancements()`	Add custom SCSS to theme
✓	`cpal_export_scss()`	Export SCSS variables

Utilities (6 functions)

Status	Function	Description
✓	`setup_cpal_google_fonts()`	Set up Google Fonts
✓	`cpal_font_family()`	Get current font family
✓	`cpal_font_family_fallback()`	Get fallback font stack
✓	`save_cpal_plot()`	Save plot with proper sizing
✓	`add_cpal_logo()`	Add logo to ggplot
✓	`check_plot_accessibility()`	Check plot accessibility

Quick Reference

Task	Function	Example
Apply theme	`theme_cpal()`	`+ theme_cpal()`
Color scale	`scale_color_cpal()`	`scale_color_cpal("main_3")`
Get colors	`cpal_colors()`	`cpal_colors("midnight_seq_5")`
Save plot	`save_cpal_plot()`	`save_cpal_plot(p, "file.png")`
Create table	`cpal_table()`	`cpal_table(data)`
Start project	`start_project()`	`start_project("name", "analysis")`

Next Steps

Now that you have cpaltemplates set up, explore these guides:

Colors & Palettes - Deep dive into the color system
Themes & Styling - Customize your visualizations
Project Setup - Create standardized project structures
ggplot2 Gallery - Example charts with code
Highcharter Gallery - Interactive chart examples