Theming API

Fuegokit React's theming API lets you control color, spacing, typography, and many other aspects of your application.
StorybookFigma
Access to Fuegokit npm packages, source code repositories, and some content is limited to Appfire staff. Log in with Slack to continue.

Theming in Fuegokit React is made possible by sets of design tokens that are defined in Fuegokit Tokens.

Color, spacing, typography, border radii, and other decisions are combined to create ecosystem-specific themes.

In Fuegokit React, you may consume those themes in a number of ways, including using a custom ThemeProvider component implemented with styled-components.

The ThemeProvider ships with a default Fuegokit theme object that defines the application's colors, spacing, typography styles, and more.

Install

npm install @fuegokit/react react react-dom styled-components


// or


yarn add @fuegokit/react react react-dom styled-components

Usage

To use the default Fuegokit React theme, you will need to wrap your application in a ThemeProvider component at the root:

// App.tsx
import {ThemeProvider} from '@fuegokit/react'


function MyApp() {
  return (
    <ThemeProvider>
      <div>An actual application here...</div>
    </ThemeProvider>
  )

When you wrap your application in ThemeProvider, your application has access to Fuegokit React's default theme object, which includes color palettes, type scale, font stacks, breakpoints, border radius values, and more. See the theme reference page.

Using the default Fuegokit theme

When your application is wrapped in ThemeProvider, Fuegokit React's theme object is directly accessible to your components.

import {Box} from '@fuegokit/react'


<Box sx={{textShadow: "shadow.overlay"}} />

Do

Use the default theme from the same context object that ships with Fuegokit React.

import {theme, Box} from '@fuegokit/react'


<Box sx={{textShadow: theme.shadows.shadow.overlay}} />

Don't

Don't style components by hand using other instances of the theme object or by accessing the theme object directly

To over-ride styles, use the `sx` prop.

Color modes and color schemes

Fuegokit React treats color-modes and color-schemes as first-class citizens.

This allows us to put accessibility at the forefront of the way we design and build interfaces with Fuegokit.

A "color mode" refers to whether an application is using day, night, or auto mode (e.g., it is synced with the user's operating system.)

A "color scheme" refers to a collection of colors that can be used for a particular color mode. By default, light and dark schemes are included with the default theme, but creating additional color schemes and color systems is possible.

We follow the standards bodies' definitions of color modes and color schemes. Read more about how browsers handle color modes here.

Adding color mode support

By default, Fuegokit React is in day mode, when no value is passed to the colorMode prop:

import {ThemeProvider, Text} from '@fuegokit/react'


function App() {
  return (
    // colorMode can be 'day', 'night', or 'auto'
    <ThemeProvider>
      <Text color="text.default">Some text here</Text> // resolved value is always #172B4D
    </ThemeProvider>
  )

To add color mode support to your applications or components, use the colorMode prop in the ThemeProvider component:

// App.tsx
import {ThemeProvider, Text} from '@fuegokit/react'


function App() {
  return (
    // colorMode can be 'day', 'night', or 'auto'
    <ThemeProvider colorMode="auto">
      <Text color="text.default">Some text here</Text> // resolved value #172B4D or #B6C2CF, depending on user's system
      preferences

Try it out. Change colorMode from 'day' to 'night', or to respect your current system preferences, 'auto':

Fuegokit React uses standard browser definitions for "color modes" and "color schemes". Available color modes are `night`, `day`, and `auto`. At this time, available color schemes are `dark`, and `light`. Read more about how browsers handle color modes here.

CSS in server-side rendered applications

If your application calls for rendering React components client- and server-side, follow styled-component's server-side rendering instructions to avoid the flash of unstyled content for server-rendered React components.

Customizing Fuegokit's default theme

In order to customize the default theme, use deepmerge and pass your custom theme object into the ThemeProvider component using the theme prop:

import {ThemeProvider, theme} from '@fuegokit/react'
import deepmerge from 'deepmerge'


const myCustomTheme = deepmerge(theme, {
  fonts: {
    normal: 'Playfair Display'
  }
})

Make sure your theme shares the same object keys as the default theme object. Using deepmerge for this purpose is recommended.

See also