Theming

ThemeProvider

To give components access to the theme object, you must add ThemeProvider to the root of your application:

import {ThemeProvider} from '@primer/react'

function App() {
  return (
    <ThemeProvider>
      <div>...</div>
    </ThemeProvider>
  )
}

ThemeProvider comes with a default theme object that includes colors, spacing, fonts, etc. for building applications at GitHub.

Referencing theme values

You can reference theme values in your application using the theme object.

You can use the theme object to reference theme values from inside any function component nested under the ThemeProvider:

import {theme, ThemeProvider} from '@primer/react'

function Example() {
  // theme.colors.canvas.default
}

function App() {
  return (
    <ThemeProvider>
      <Example />
    </ThemeProvider>
  )
}

Color modes and color schemes

The terms "color mode" and "color scheme" are often used interchangeably. However, in Primer React, they are two separate (but related) concepts.

The "color mode" of an application can be either day, night, or auto (i.e. synced with the operating system).

A "color scheme", on the other hand, is a collection of colors that can be associated with a color mode. The default theme includes several color schemes, including light, dark, and dark_dimmed. By default, the light scheme is displayed when the application is in day mode and the dark scheme is displayed in night mode.

Setting the color mode

By default, Primer React is in day mode. To change the color mode, use the colorMode prop on ThemeProvider or the setColorMode function from the useTheme hook:

colorMode prop

import {ThemeProvider} from '@primer/react'

function App() {
  return (
    // colorMode can be "day" (default), "night", or "auto"
    <ThemeProvider colorMode="auto">
      <div>...</div>
    </ThemeProvider>
  )
}

setColorMode function

import {useTheme} from '@primer/react'

function Example() {
  const {setColorMode} = useTheme()
  return <button onClick={() => setColorMode('auto')}>Activate auto mode</button>
}

preventSSRMismatch prop

If you are doing server-side rendering, pass the preventSSRMismatch prop to ensure the rendered output from the server and browser match even when they resolve "auto" color mode differently.

<ThemeProvider colorMode="auto" preventSSRMismatch>
  ...
</ThemeProvider>

Setting color schemes

To choose which color schemes will be displayed in day and night mode, use the dayScheme and nightScheme props on ThemeProvider or the setDayScheme and setNightScheme functions from the useTheme hook:

dayScheme and nightScheme props

import {ThemeProvider} from '@primer/react'

function App() {
  return (
    // The default theme includes `light`, `dark`, and `dark_dimmed` schemes
    <ThemeProvider dayScheme="light" nightScheme="dark_dimmed">
      <div>...</div>
    </ThemeProvider>
  )
}

setDayScheme and setNightScheme functions

import {useTheme} from '@primer/react'

function Example() {
  const {setDayScheme, setNightScheme} = useTheme()
  return <button onClick={() => setNightScheme('auto')}>Activate auto mode</button>
}

Creating local color scheme variables

If you need to use a color that is not defined in the theme, avoid hard coding the color value like this:

function Example() {
  return (
    // BAD: #aaa may not look good in all color schemes
    <div style={{backgroundColor: '#aaa'}}>Hello world</div>
  )
}

Instead, use the useColorSchemeVar hook to create a local variable that will update based on the active color scheme:

import {useColorSchemeVar} from '@primer/react'
import {colors} from '@primer/primitives'

function Example() {
  // GOOD: The value of `customBg` changes based on the active color scheme
  const customBg = useColorSchemeVar({
    light: colors.light.scale.gray[1],
    dark: colors.dark.scale.gray[9],
    dark_dimmed: colors.dark_dimmed.scale.gray[2],
  })
  return <div style={{backgroundColor: customBg}}>Hello world</div>
}