Unified theming with brand.yml • bslib

Shiny for R now supports brand.yml, a single YAML file that unifies visual theming across your projects. Define colors, fonts, and logos once in a YAML file, then use them consistently across Shiny apps, Quarto projects, and more.

What is brand.yml?

brand.yml is a specification for managing visual branding through a single YAML file. It simplifies brand management and theming by consolidating your visual identity—colors, typography, and styling—into one easy-to-maintain location.

At its most basic, a _brand.yml file includes metadata (meta) about the company or brand, its logos (logo), color palette, theme, and the fonts and typography settings used by the brand.

Here’s a simple _brand.yml file:

meta:
  name: brand.yml
  link: https://posit-dev.github.io/brand-yml

logo:
  small: brand-yml-icon.svg
  medium: brand-yml-tall.svg
  large: brand-yml-wide.svg

color:
  palette:
    orange: "#FF6F20"
    pink: "#FF3D7F"
  primary: orange
  danger: pink

typography:
  fonts:
    - family: Open Sans
      source: google
  base: Open Sans

This same file can be used to theme your Shiny apps as well as Quarto projects. And brand.yml isn’t just for corporate branding—you can also use brand.yml to create custom themes for your personal or team-specific projects. Create a _brand.yml file to match a specific journal or conference style.

When used with bslib, simply place the _brand.yml file in your project directory, and bslib will automatically apply the branding to your Shiny app.

Try brand.yml

bslib includes an example app that you can use to try out brand.yml features or that can be helpful as you develop your own _brand.yml file. To run the app use shiny::runExample().

shiny::runExample("brand.yml", package = "bslib")

To use the app as a template, create a new directory for your own app and then copy the bslib example app to that directory

new_app_dir <- "my-brand" # path to your app
template <- fs::path_package("bslib", "examples-shiny/brand")

# Copy the template files into your new app directory
fs::dir_copy(template, new_app_dir)

Once created, open app.R and _brand.yml for editing.

file.edit(fs::path(new_app_dir, "app.R"))
file.edit(fs::path(new_app_dir, "_brand.yml"))

Basic usage

Automatic discovery

To use a brand.yml file like the example above, save the file as _brand.yml and include it in the directory containing your Shiny app.

# Automatically find `_brand.yml` in app directory or its parent directories
ui <- page_fluid(
  theme = bs_theme()  # No additional configuration needed
)

When your app uses uses theme = bs_theme(), any of the bslib::page_*() functions, or bslib theming under-the-hood, bslib will automatically

search for a _brand.yml file in the current directory or in a _brand/ or brand/ directory,
if not found, check parent directories for the _brand.yml file (possibly also in _brand/ or brand/), and
apply the branded theming if a _brand.yml file is found.

Explicit configuration

You can also be more explicit about brand.yml usage.

Use brand = TRUE to find _brand.yml in app dir or its parents, or fail otherwise.

ui <- page_sidebar(
  theme = bs_theme(brand = TRUE)
)

Provide brand with a direct path to a brand.yml file, useful when the file has a special name or is stored in a central location.

ui <- page_sidebar(
  theme = bs_theme(brand = "path/to/brand.yml")
)

Use a list to define brand settings inline, useful to quickly theme a small app.

ui <- page_sidebar(
  theme = bs_theme(
    brand = list(
      color = list(primary = "#FF6F20", danger = "#FF3D7F"),
      typography = list(
        fonts = list(
          list(family = "Open Sans", source = "google")
        ),
        base = "Open Sans"
      )
    )
  )
)

Finally, you can ignore an existing _brand.yml file and apply no branding.

ui <- page_sidebar(
  theme = bs_theme(brand = FALSE)
)

YAML configuration

Many places across the R Markdown ecosystem use bslib for theming. Anywhere that theme is passed to bslib, you can use the same techniques mentioned above, even in YAML.

Bootstrap 5 Required

Theming with brand.yml works best with Bootstrap 5. For best results, be sure to include version: 5 under theme.

In the most basic case, place a _brand.yml in the project folder and ensure that the document uses Bootstrap 5.

output:
  html_document:
    theme:
      version: 5

Use brand: TRUE to automatically find _brand.yml or throw an error if not found within the project.

output:
  html_document:
    theme:
      version: 5
      brand: true

Provide brand with a direct path to a brand.yml file.

output:
  html_document:
    theme:
      version: 5
      brand: "path/to/brand.yml"

Define brand settings directly inline in the brand key.

output:
  html_document:
    theme:
      version: 5
      brand:
        color:
          primary: "#FF6F20"
          danger: "#FF3D7F"
        typography:
          fonts:
            - family: "Open Sans"
            source: "google"
          base: "Open Sans"

Ignore an existing _brand.yml file and apply no branding with brand: false.

output:
  html_document:
    theme:
      version: 5
      brand: false

Learn more

This article has barely scratched the surface of all of the information and customizations that brand.yml includes. We encourage you to learn more about brand.yml and its features at the official brand.yml website. We also invite you to leave feedback and ask questions in the brand.yml discussion board.

Visit these pages to learn more about using brand.yml with other projects:

As a brand new project, most large language models (LLMs) don’t know anything about brand.yml (yet), but they can still be useful with the right prompt. We’ve created a small but complete description of brand.yml that you can use to help teach an LLM about brand.yml. Read more in the Creating a brand.yml with an LLM article on the brand.yml website.