Primer Brand defines various global styling defaults using CSS variables, while also allowing app-level customization through its ThemeProvider.

CSS variables are available for most styling dimensions such as typography, color and sizing. They are defined in the primary stylesheet: main.css.

ThemeProvider extends theming capabilities at runtime by enabling real-time color mode switching among other things.

Using the CSS stylesheet and ThemeProvider in tandem is crucial to make theming work correctly.

Configure the ThemeProvider

The ThemeProvider should wrap your React application root to enable theming correctly. It can also be nested to apply isolated behavior to children.

import {ThemeProvider} from '@primer/react-brand'
function App() {
return (

Load the stylesheet

The stylesheet contains all of the required rules for design tokens and components. It also includes a CSS reset, so we recommend loading this as early as possible in your HTML <head> to minimize undesirable rendering behavior.

import '@primer/react-brand/lib/css/main.css'

Set a color mode

Primer Brand supports the following color modes through a dedicated prop by applying HTML data-* attributes:

ThemecolorMode prop valueData attribute applied

The ThemeProvider applies the data attributes and handles state-changes internally.

ThemeProvider will apply light mode by default if the colorMode is not specified. This is recommended for top-level placement.

The following example demonstrates how light mode will enable by default, and can also be changed to dark declaratively:

Locking the color mode

For tighter control over appearance - such as forcing areas of a layout to appear in dark mode - we recommend nesting ThemeProvider and explicitly applying a color mode.