Theming

You can define a theme by providing custom values for themeable design tokens. There are three categories of themeable tokens: typography, color, and border radius.

Typography tokens

The custom values you set for typography tokens (such as fontFamilyBase) are applied globally in the entire application, including visual contexts. When setting custom values for font families, ensure that you also provide the corresponding font assets.

For example, a theme with a new value for fontFamilyBase looks like the following:

const theme = {
   tokens: {
        fontFamilyBase: "'Helvetica Neue', Roboto, Arial, sans-serif",
   },
};

Border radius tokens

The values you set for border radius tokens (such as borderRadiusButton) are applied globally across the entire UI, including visual contexts.

For example, a theme with a new value for borderRadiusButton looks like the following:

const theme = {
   tokens: {
        borderRadiusButton: "4px",
   },
};

Color tokens

You can set custom values for color tokens globally, and for each visual context. If you don't explicitly specify a custom value for a visual context, the default Cloudscape value will be applied.

You can also specify a value for both light and dark mode. Here is an example:

const theme = {
   tokens: {
      // Values are applied globally, except for visual contexts
      colorBackgroundLayoutMain: {
          // Specify value for light and dark mode
          light: 'white',
          dark: 'blue'
      }
      // Shorter syntax to apply the same value for both light and dark mode
      colorTextAccent: '#0073bb',
   },
   contexts: {
      // Values for visual contexts. Unless specified, default values will be applied
      'top-navigation': {
         tokens: {
            colorTextAccent: '#44b9d6',
         },
      },
      header: {...}
      flashbar: {...}
      alert: {...}
   },
};

You can theme Cloudscape components by generating a stylesheet with your custom theme as part of your build process, and include it in your application on top of the default Cloudscape styles.

Generate a themed stylesheet

Use the generateThemeStylesheet function from the theming module of the @cloudscape-design/components-themeable package as part of your build process. You must provide a selector.

import { join } from 'path';
import { writeFileSync } from 'fs';
import { generateThemeStylesheet } from '@cloudscape-design/components-themeable/theming';

const theme = {...};
const stylesheet = generateThemeStylesheet({ theme, selector: "body" });

writeFileSync(join(__dirname, './app-theme.css'), stylesheet);

You can now import your generated CSS file in your application so that it loads after the default Cloudscape styles. The imported theme will override the theme for all Cloudscape components rendered under the elements targeted by the selector. The selector can be scoped to "body" or any specific element where the theme should be scoped to.

Generate a themed stylesheet during runtime

The generateThemeStylesheet function is also available during runtime from the theming module of the @cloudscape-design/components-themeable module. This lets you generate and inject a stylesheet during runtime to override Cloudscape styles. You must provide a selector.

import { Theme, generateThemeStylesheet } from '@cloudscape-design/components/theming';

const theme: Theme = {...};
const styles = generateThemeStylesheet({ theme, selector: "body" });

const stylesheet = new CSSStyleSheet();
stylesheet.replaceSync(styles);
document.adoptedStyleSheets.push(stylesheet);

Themes can also be applied during runtime using the applyTheme function. This automatically creates an inline <style> element and attaches it to the document. When using applyTheme, make sure your Content Security Policy supports inline stylesheets by adding Content-Security-Policy: style-src: 'self' 'unsafe-inline';.

import { Theme, applyTheme } from '@cloudscape-design/components/theming';

const theme: Theme = {...};
const { reset } = applyTheme({ theme, selector: "body" });
// Use the reset method to remove the custom theme

Refer to the demo pages and the theme switcher in the top of the navigation bar to try out runtime theming.

Build-time vs runtime theming

We recommend build-time theming because:

• It offers better performance: runtime theming requires to bundle a large file that contains default theme definitions, so that updated styles can be generated. Generating styles is also CPU-heavy, so generating runtime styles can block the main thread.

• It provides better support for server-side rendering (SSR) and server-side generation (SSG): for SSR or SSG applications, runtime theming is applied only after hydration, providing a sub-optimal user experience as the user sees the non-themed application first.

Use runtime theming only if your application themes must be dynamically defined or updated for each customer on the frontend.