styled-components-theming

Application-wide theming with component-level isolation for styled-components.

Status

| Category | Status | |----------|---------------------------------------------------------------------------------------------------------------------------------------------| | Version | | | Build | | | License | |

Introduction

When we say "theming", we think of a uniform design, applied application-wide. Like most styling solutions, styled-components has facilities for theming, allowing us to pass a theme object implicitly to all styled components.

While this approach is how most frameworks handle theming, we feel this approach lacks nuance. It is true that the foundation of every design is shared sizes, colors, fonts and so on, those things alone do not make a functioning stylesheet. The reality is that most component's styles are very messy and a great deal of detail work is needed to get the desired result.

Instead of thinking of theming in two layers, the global, shared theme and the isolated, technical implementation of concrete stylesheets, we want to propose a slightly different approach.

We think of theming consisting of three layers: The global theme, the local theme that defines which parts of the global theme should be used and in what capacity, and the technical implementation of the stylesheet itself.

In our view, the three layers should concern themselves with the following responsibilities:

The global theme should provide basic shared values of the design, like a unit length, color palette, font families, sizes and weights and so on. It does not know about any particular components and their details.

The local theme is derived from the global theme and is specific to one component. It is responsible for turning the abstract global theme into a theme tailored to this component. While we may define a color palette in the global theme, it is the job of the local theme to define what parts of its component use which color from the palette.

The stylesheet is derived from the local theme and its sole purpose is translating the domain-oriented local theme into CSS. It should not contain any logic.

We make this distinction to de-clutter the global theme and the stylesheet. In our experience, not having isolated local theme leads to several code smells:

• Component-specific code start accumulating in the global theme.
• As a consequence, the global theme becomes very large and increasingly nested, leading to:
  • several teams owning parts of the global theme and nobody knowing which parts are actually needed.
  • duplicated code in the global theme, because it is easier to just add what you need rather than looking for an already existing part to use.
• Special cases are handled inside the stylesheet code, making it hard to read.
  • These special cases are also duplicated because code sharing between styled components is not intuitive.

Getting started

First, install the package.

npm install @nhummel/styled-components-theming

Create the global theme and variants

To start off, you need to define the global theme. Note that there may be multiple variants of this theme. All variants share the same structure, but may contain different values. You can implement a dark mode, or re-skin your application with these.

// style/globalTheme.ts

const {
  createGlobalStyle,
  createLocalTheme,
  GlobalThemeProvider,
  useTheme
} = createGlobalTheme({
  globalThemes: {
    dark: {
      space: (units: number): string => `${units * 4}px`,
      brandColor: '#a5e',
      color: '#e3e3e3',
      background: '#222'
    },
    light: {
      space: (units: number): string => `${units * 4}px`,
      brandColor: '#a5e',
      color: '#222',
      background: '#e3e3e3'
    }
  },
  variants: [ 'dark', 'light' ] as const, // `as const` is for Typescript only
  defaultVariant: 'dark' as const // `as const` is for Typescript only
});

export {
  createGlobalStyle,
  createLocalTheme,
  GlobalThemeProvider,
  useTheme
};

The global theme can be an arbitrary object. The defaultVariant is used when the application starts.

You will need the values returned, so make sure to export them.

If you use TypeScript, make sure to define variants and defaultVariant as const, this will allow the library to infer the types of later functions correctly.

Add the GlobalThemeProvider to your application

In the example above, you can see that createGlobalTheme returns a React component GlobalThemeProvider. You need to add this context provider to your application somewhere high up in the tree. All components using local themes must be below it.

import { GlobalThemeProvider } from './style/globalTheme';

const App: FunctionComponent<AppProps> = function ({
  Component,
  pageProps
}): ReactElement {
  return (
    <GlobalThemeProvider>
      <Component { ...pageProps } />
    </GlobalThemeProvider>
  );
};

export default App;

Create component-level themes

You can now use createLocalTheme to create isolated component-level themes.

import { globalThemeContext } from './style/globalTheme';

const { from, get } = createLocalTheme(
  ({ globalTheme, variant }) => {
    const { brandColor, background } = globalTheme;
    let { color } = globalTheme;

    if (variant === 'light') {
      color = background;
    }

    return {
      color,
      background: brandColor,
      padding: globalTheme.space(2)
    };
  }
);

The first parameter is a factory that receives the current global theme and the name of the current variant and returns the local theme. The local theme can be an arbitrary object as well, but as a general rule it is best that the values are all either strings or have a toString method.

Note that you can execute logic in the factory and make decisions based on the variant. While only the theme corresponding to the variant is passed to the factory, in some cases, you might want to switch things around.

Using the local theme

The createLocalTheme function returns a function called from. You can use this function to reference the local theme in styled components:

import { createLocalTheme } from './style/globalTheme';

const { from } = createLocalTheme(({ globalTheme }) => {/* ... */
})

const Banner = styled.div`
  color: ${ from(theme => theme.color) };
  background-color: ${ from(theme => theme.background) };
  padding: ${ from(theme => theme.padding) };
`;

The from function receives the local theme as its only argument.

Note: The from function call must be the only value in the interpolation. It can't be wrapped in another function. This won't work:

const Headline = styled.span<{ level: number }>`
  font-size: ${({ level }) => from(theme => theme.size(level))};
`;

If you need to use the local theme inside a function, use the get function.

Using component props

The from function provides a nice shorthand if you just want to access parts of the local theme. It can't be used inside a function though. If you need to access component props, you can use the get function returned by createLocalTheme.

import { createLocalTheme } from './style/globalTheme';

const { get } = createLocalTheme(({ globalTheme }) => {/* ... */
})

const Button = styled.button<{ inverted: boolean }>`
  background-color: ${props => props.inverted ? get(theme => theme.backgroundColor.inverted) : get(theme => theme.backgroundColor.normal)};
  color: ${props => props.inverted ? get(theme => theme.color.inverted) : get(theme => theme.color.normal)};
`;

Switching between variants & useTheme

The call to createGlobalTheme also returns a hook called useTheme. This hook can be used to obtain information about variants, access the global theme directly, or switch the current variant.

import { useTheme } from './style/globalTheme';

const ThemeSwitch: FunctionComponent = () => {
  const {
    availableVariants,
    variant,
    globalTheme,
    switchVariant
  } = useTheme();

  return (
    <button
      onClick={
        (): void => switchVariant('light')
      }
    >
      Switch theme
    </button>
  );
};

Creating global styles with createGlobalStyle

styled-components provides a utility function for inserting global CSS rules called createGlobalStyle. While you can still use this utility unimpeded by this library, you may want to access the global theme from these global styles.

To achieve this, use the createGlobalStyle function returned from createGlobalTheme. You can use the resulting component anywhere in your app, below the GlobalThemeProvider.

import { createGlobalStyle, GlobalThemeProvider } from './style/globalTheme';

const GlobalStyle = createGlobalStyle`
  * {
    box-sizing: border-box;
  }

  body {
    font-family: 'Dosis', sans-serif;
    font-size: ${({ globalTheme }): string => globalTheme.fontSize};
    background-color: ${({ globalTheme }): string => globalTheme.backgroundColor};
    color: ${({ globalTheme }): string => globalTheme.color};
  }
`;

const App: FunctionComponent<AppProps> = function ({
  Component,
  pageProps
}): ReactElement {
  return (
    <GlobalThemeProvider>
      <GlobalStyle />
      <Component { ...pageProps } />
    </GlobalThemeProvider>
  );
};

export default App;

Contributing

Feel free to open an issue or a pull request.

Running quality assurance

npx roboter