How to apply your brand’s theme to AWS UI components

The AWS UI component library offers a powerful, mobile responsive, and intuitive user interface. Leveraging Amazon’s research into customer experience, the customer-obsessed tech giant does not fall short. However, the UI library formally lacks one important feature: branding. This article will cover how to apply your own brand despite a lack of formal support.

The AWS UI team did an outstanding and admirable job of stripping Amazon’s trademark colors and fonts from their UI and open-sourcing the components for the community. This move will allow third parties to rapidly deliver new features. I was able to migrate my entire portfolio and sprite sheet to GIF conversion application to TypeScript and the new UI in about a week. An open source policy also offers reciprocal benefits. Customers of AWS can not contribute bug fixes, feature implementations, and performance enhancements directly back to AWS.

During this complex transition process from a close-source, single brand library to an open-source package, the AWS UI components have not yet adopted customization. However disappointing this may be for your organization, it’s understandable that scope creep did not take top priority. I am here to relieve your concerns. You can change the theme of your AWS UI components, and this implementation is open-source as well.

What’s the minimum I need to get started? ⌚

If you’re ready to get started styling your AWS UI components quickly and easily, you can install the awsui-theme NPM package.

Wrap your entire application (or just the part you want styled) in the AwsuiTheme component, and pass props to the AwsuiTheme for each design token you want changed.

import AwsuiTheme from 'awsui-theme';
import Home from './home';
export default function MyApp() {
return (
<AwsuiTheme colorTextAccent="red">
<Home />
</AwsuiTheme>
);
}

The above code sample will render the Home component, replacing all instances of the AWS UI component text accent color with red. For most applications, you will want to write the entire application with AwsuiTheme, the same way you wrap the entire application with React Query, React Router, or Redux providers.

How does it work? 🤔

The AWS UI component library does not yet (and may never) support React context for injecting themes into individual components. The AwsuiTheme component works by taking your provided theme colors and changing the value of the AWS UI CSS variables for all child nodes.

When you wrap your code in the AwsuiTheme component, like as follows, it mounts a wrapper with a unique class name.

// app.tsx
function MyApp() {
return (
<AwsuiTheme colorTextAccent="red">
<Home />
</AwsuiTheme>
);
}

Your browser’s CSS now contains the global AWS UI CSS variables, as injected by @awsui/global-styles. For example, you may have --color-text-accent: blue. Additionally, the AwsuiTheme component has mounted a new DOM node with a unique class name, e.g. .AwsuiTheme-1. That class name contains overrides of the global AWS UI CSS variables. In the above example, it would contain something like --color-text-accent: red. As a result, all child nodes of this AwsuiTheme will be red whenever they reference the --color-text-accent CSS variable. That is precisely how the AWS UI components set their colors today.

:root {
--color-button-primary: blue;
}
.AwsuiTheme-1 {
--color-button-primary: red;
}

Conclusion 🔚

If you have any questions or feedback, please leave them in the comments below.

To read more of my columns, you may follow me on LinkedIn and Twitter, or check out my portfolio on CharlesStover.com.

Senior front end engineer / charlesstover.com

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store