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
-
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
.