#Theming

Eufemia supports theming through design tokens and theme packages. Together, these let you adapt the look and feel of your application to match different brands or visual modes.

#Theme component and useTheme hook

Eufemia has theming helpers, that lets you create nested theming solutions.

It provides a React context for theme information, and a helper component to set the active theme and surface.

#Run your application with a different theme

Themes are independent style packages that should not be imported in parallel, but rather one or the other.

You can easily switch the static import of styles to a different theme:

import '@dnb/eufemia/style/core' // or /basis when "dnb-core-style" is used
- import '@dnb/eufemia/style/themes/ui'
+ import '@dnb/eufemia/style/themes/eiendom'

Read more about how to import styles.

However, giving the user the ability to switch a theme during runtime is a different challenge.

The Eufemia Portal (documentation) uses gatsby-plugin-eufemia-theme-handler to handle it both in development and production mode.

In future we may provide a built-in solution for runtime theme switching.

#Design tokens

Design tokens are CSS custom properties that store colors and other values used by Eufemia components.

Unlike plain CSS variables such as --color-sea-green that map directly to a fixed color, tokens like --token-color-text-warning describe a role. The actual color behind the token depends on the active theme and surface, making your styles portable across visual contexts.

#Basic usage

Use the var() function to reference a token in your CSS:

.my-component {
  background-color: var(--token-color-background-neutral-subtle);
  color: var(--token-color-text-neutral);
  border: 1px solid var(--token-color-stroke-neutral);
}

.my-component__title {
  color: var(--token-color-text-neutral);
}

.my-component__action {
  background-color: var(--token-color-background-action);
  color: var(--token-color-text-action-inverse);
}

#Using tokens in your own styles

When writing custom component styles, you can use design tokens with the var(--token-*) syntax. For example:

.my-component__title--warning {
  color: var(--token-color-text-warning);
}

#Dark surfaces

Use surface="dark" on the Theme component to tell Eufemia that an area has a dark background. Components inside that area will automatically pick the right colors. The ondark tokens are the color values they switch to.

For example, a button that normally uses --token-color-background-action-hover will switch to --token-color-background-action-hover-ondark when surface="dark" is active.

Read more about ondark tokens and how to use them in custom components in the Design Tokens section.

Read more about the surface property.

#Dark mode / Color scheme

Use the colorScheme prop on the Theme component to control dark and light mode.

When set to "auto", it follows the user's system color preference unless overridden by a parent theme or application setting. It uses the prefers-color-scheme media query to detect the system preference.

Dark mode tokens are not included in the default theme import. You need to import them separately:

import { Theme } from '@dnb/eufemia/shared'

// Required: import dark mode tokens
import '@dnb/eufemia/style/themes/ui/ui-theme-dark-mode--isolated.min.css' // If style isolation is used

render(
  <Theme colorScheme="auto">
    <App />
  </Theme>
)

When the eufemia-theme__color-scheme--dark class is active, the dark tokens override the same CSS custom property names with dark-appropriate values. For example, --token-color-background-page-background switches from --dnb-greyscale-0 (white) to --dnb-greyscale-1000 (dark).

Read more about the colorScheme property, including preventing dark mode flash (FOUC) for SSR considerations.