Abyss theming supports changing colors, spacing, box shadows, font families, font sizes, and many other properties. Themes let you apply a consistent tone to your app. It allows you to customize all design aspects of your project in order to meet the specific needs of your business or brand. To configure the theme, wrap your app with a ThemeProvider component.

ThemeProvider

ThemeProvider uses Emotion's theming context to pass the theme down to the components, so you need to make sure that ThemeProvider is a parent of the components you are trying to customize.

createTheme

The createTheme tool is used to create a theme object to then be passed to the theme prop on the ThemeProvider. This function takes one of two preset theme names, 'uhc' or 'optum', and an optional theme override object as arguments.

import { ThemeProvider } from '@uhg-abyss/web/ui/ThemeProvider';
import { createTheme } from '@uhg-abyss/web/tools/theme';

const theme = createTheme('uhc');

const App = () => {
  return <ThemeProvider theme={theme}>...</ThemeProvider>;
};

Function-based theme prop

ThemeProvider's theme prop can also accept a function that receives the parent theme (or null if no parent exists). This is useful for nested theme contexts where you want to inherit and extend the parent theme using extendTheme.

import { ThemeProvider } from '@uhg-abyss/web/ui/ThemeProvider';
import { createTheme, extendTheme } from '@uhg-abyss/web/tools/theme';

const baseTheme = createTheme('uhc');

const App = () => {
  return (
    <ThemeProvider theme={baseTheme}>
      <MainContent />

      {/* Nested provider inherits parent customizations */}
      <ThemeProvider
        theme={(parentTheme) =>
          extendTheme(parentTheme, {
            theme: {
              colors: { 'core.color.brand.100': '#6950C3' },
            },
          })
        }
      >
        <Sidebar />
      </ThemeProvider>
    </ThemeProvider>
  );
};

Info

This pattern enables efficient CSS generation as the child theme only generates CSS variables for overridden tokens, inheriting the rest from the parent. See extendTheme for more details.

Global styles

If you need to apply custom global styles to your application, you have two options:

• Use the css property available on the theme override object on createTheme. This will attach any styles to the root element of the ThemeProvider (see Theme overrides).
• Use Emotion's Global component to define global styles that apply across your entire application outside the scope of the ThemeProvider (see below).

import { ThemeProvider, Global } from '@uhg-abyss/web/ui/ThemeProvider';
import { createTheme } from '@uhg-abyss/web/tools/theme';

const globalStyles = {
  body: {
    backgroundColor: '#f0f0f0',
  },
};

const theme = createTheme('uhc');

const App = () => {
  return (
    <ThemeProvider theme={theme}>
      <Global styles={globalStyles} />
      ...
    </ThemeProvider>
  );
};

Advanced theming options

For more advanced theming scenarios, Abyss provides additional providers:

• StyleRootProvider - For applications that need fine-grained control over CSS injection or shadow DOM isolation
• NextStyleProvider - Optimized for Next.js applications with server-side rendering support

ThemeProvider Props

Name	Type	Default	Required	Description
children	React.ReactNode	-		The children components to be rendered within the ThemeProvider.
theme	CreateThemeReturn | ((parentTheme: import("/home/runner/_work/abyss/abyss/packages/abyss-...	-	-	The theme configuration for the ThemeProvider. Can be a static theme object from createTheme/extendTheme, or a function that receives the parent theme and returns a theme (for nested contexts).