theme

Amplify UI Theme

This package generates the core CSS used by Amplify UI for the web on any framework.

Amplify UI uses CSS to share styling across web frameworks

Usage

CSS

Amplify UI exports 2 CSS files:

• styles.css contains all the styling needed for Amplify UI
• theme.css contains only the default theme CSS variables

You can import the styles in a CSS file:

@import '@aws-amplify/ui/styles.css';

You can also import it in the Javascript:

import '@aws-amplify/ui/styles.css';

Typescript / Javascript

In addition to the static CSS, this package exports:

• defaultTheme: The default Theme object which Amplify UI uses for its default theme.
• createTheme: A function that takes theme customizations and returns a Theme object which contains the CSS needed to theme Amplify UI components

import { createTheme, defaultTheme } from '@aws-amplify/ui';

export const theme = createTheme({
  tokens: {
    colors: {
      brand: {
        primary: defaultTheme.colors.blue,
      },
    },
  },
  // customize the breakpoints
  breakpoints: {},
  // customize overrides like dark mode or responsive theming
  overrides: [{}],
});

// theme.css returns a string which can be written to a CSS file or placed inline in a <style> tag

Theme Structure

Tokens

The Amplify UI theme is built with Design Tokens. The structure of the Amplify UI theme tokens follows the System-UI Theme Specification. There are global design tokens that are under the top-level namespaces like colors, fontSizes, space, etc. Then there are component design tokens under the components namespace.

Breakpoints

Breakpoints allow you to set media query breakpoints for responsive design. You can then define breakpoint-specific token overrides or use the breakpoints for different layouts in Javascript.

export interface Breakpoints {
  values: {
    base: number;
    small: number;
    medium: number;
    large: number;
    xl: number;
    xxl: number;
  };
  unit: string;
  defaultBreakpoint: string;
}

You can modify default breakpoints in the createTheme method:

import { createTheme } from '@aws-amplify/ui';

const myTheme = createTheme({
  name: 'my-theme',
  breakpoints: {
    // createTheme does a deep merge with the default theme
    // so you don't have to override all the breakpoint values
    values: {
      // default unit is 'em'
      medium: 50,
    },
  },
  //...
});

Overrides

An override is a collection of design tokens that should take precedence in certain situations, like dark mode. Overrides are built into the theme configuration, but kept separate, so that Amplify UI can use CSS for overriding parts of the theme.

import { createTheme } from '@aws-amplify/ui';

export const theme = createTheme({
  name: 'my-theme',
  overrides: [
    {
      colorMode: 'dark',
      tokens: {
        colors: {
          neutral: {
            10: { value: defaultTheme.tokens.colors.neutral[100].value },
            20: { value: defaultTheme.tokens.colors.neutral[90].value },
            40: { value: defaultTheme.tokens.colors.neutral[80].value },
            80: { value: defaultTheme.tokens.colors.neutral[40].value },
            90: { value: defaultTheme.tokens.colors.neutral[20].value },
            100: { value: defaultTheme.tokens.colors.neutral[10].value },
          },
          black: { value: '#fff' },
          white: { value: '#000' },
        },
      },
    },
    {
      breakpoint: 'large',
      tokens: {
        space: {
          small: { value: '1rem' },
          medium: { value: '2rem' },
          large: { value: '3rem' },
        },
      },
    },
  ],
});

You can override design tokens in CSS by using a media query or adding extra selectors to [data-amplify-theme="{theme.name}"].

@media (prefers-color-scheme: dark) {
  [data-amplify-theme='my-theme'] {
    --amplify-colors-black: #fff;
    --amplify-colors-white: #fff;
  }
}

[data-amplify-theme='my-theme'].disco {
  --amplify-colors-font-primary: pink;
}