awsui-theme v1.0.5

AWS UI Theme

The AwsuiTheme component allows you to easily apply your brand's theme to your AWS UI components.

Looking for dark mode? Check out awsui-dark-mode.

• Install
• Use
• Props
• AwsuiThemeRootSelector
• F.A.Q.
  • CollectionPreferences

Install

• npm install awsui-theme or
• yarn add awsui-theme

Use

To use a custom AWS UI theme, wrap the AwsuiTheme component around your application. While AwsuiTheme does not currently use React contexts, this wrapper would most likely be placed alongside your React context providers, such as React Router or Redux.

import AwsuiTheme from 'awsui-theme';

export default function App() {
  return (
    <AwsuiTheme>
      <Home />
    </AwsuiTheme>
  );
}

Props

The AwsuiTheme takes any number of props specifying design tokens for your theme. These props are more or less equivalent to the design tokens you would find in the @awsui/design-tokens package.

With TypeScript support, the known design tokens should auto-complete in your development environment. There may be more, unknown design tokens that do not auto-complete. You may specify any value as a prop, and the AwsuiTheme component will attempt to find that design token in the document.

For example, if the CSS variable you want to manipulate is called --color-test-xyz, but colorTest does not auto-complete as a prop, you may still specify it anyway: colorTest="red". The component will scan the document for CSS variables named --color-test-xyz and change those values for all child nodes.

An example AwsuiTheme implementation that changes the primary action color from blue to red may look like this:

import AwsuiTheme from 'awsui-theme';

export default function App() {
  return (
    <AwsuiTheme colorTextAccent="red">
      <Home />
    </AwsuiTheme>
  );
}

AwsuiThemeRootSelector

You may want to apply your theme to a different element than the wrapper created by the AwsuiTheme component. For example, in order to support CollectionPreferences, you may want to apply your theme to your body element.

To do this, wrap your AwsuiTheme component in the AwsuiThemeRootSelector context. This allows you to specify the CSS selector to which your theme is applied.

import AwsuiTheme, { AwsuiThemeRootSelector } from 'awsui-theme';

export default function App() {
  return (
    <AwsuiThemeRootSelector.Provider value="body">
      <AwsuiTheme colorTextAccent="red">
        <Home />
      </AwsuiTheme>
    </AwsuiThemeRootSelector.Provider>
  );
}

In the above example, the --color-text-accent CSS variable is now applied to body instead of .awsui-theme-1.

F.A.Q.

CollectionPreferences

What do I do if my CollectionPreferences component is still unthemed?

AWS UI mounts the CollectionPreferences as a child node of your body element. As a result, it falls outside of the wrapper generated by the AwsuiTheme component.

Currently, AWS UI does not offer a way to mount the CollectionPreferences component anywhere other than the body element. To style the CollectionPreferences component, you must apply your AWS UI theme to your body element. To do this, see AwsuiThemeRootSelector.