@dnb/eufemia/docs/uilib/usage/customisation/theming/theme.md

DNB Eufemia Design System UI Library

---
title: 'Theme'
description: 'The Theme component is a helper component that lets you create nested theming solutions.'
version: 11.0.0
generatedAt: 2026-04-21T13:57:53.954Z
checksum: 090b7d977ba4be5e2c4c04d199a30a4048416c59f443a56985df2f80629d9c40
---

# Theme

## Description

The Theme component is a helper component that lets you create nested theming solutions.

**NB:** `<Theme>` wraps its children in a `div` by default. Use e.g. `element="span"` to change the wrapper element, or use `Theme.Context` to skip the wrapper entirely (see below).

```tsx
import { Theme, useTheme } from '@dnb/eufemia/shared'

const Component = () => {
  const themeName = useTheme()?.name
  return 'My Component'
}

render(
  <Theme name="sbanken">
    <App>
      <MyComponent />
    </App>
  </Theme>
)
```

From CSS you can use it as so:

- `.eufemia-theme__sbanken`
- `.eufemia-theme[data-name="sbanken"]` (alternative)

**CSS**

```css
.eufemia-theme__sbanken .additional-selector {
  --color-sea-green: var(--sb-color-purple-alternative);
}
```

**SCSS**

```scss
:global(.eufemia-theme__sbanken) {
  .additional-selector {
    --color-sea-green: var(--sb-color-purple-alternative);
  }
}
```

### React Hook `useTheme`

For accessing the theme context, you can use the `useTheme` Hook. It returns the theme context, with an addition of boolean constants like `isSbanken`.

```tsx
import { Theme, useTheme } from '@dnb/eufemia/shared'

const Component = () => {
  // Result: { name: 'sbanken', isUi: false, isSbanken: true, isEiendom: false }
  const theme = useTheme()
  const { name, isUi, isSbanken, isEiendom } = theme || {}
  return null
}

render(
  <Theme name="sbanken">
    <App>
      <MyComponent />
    </App>
  </Theme>
)
```

**NB:** If no context is given, the hook will return `null`.

### Theme.Context

You can use `Theme.Context` to provide theme properties to children without adding a wrapper element. This is useful in cases where you don't want to add an extra DOM element, but still want to provide theme context to the children.

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

render(
  <Theme.Context>
    Children that receive theme context without an extra wrapper element.
  </Theme.Context>
)
```

#### `surface` property

The `surface` property can be used to adjust the component's appearance based on the background. It accepts three values: `dark`, `light`, and `initial`.

- Use `dark` when the content is placed on a dark surface.
- Use `light` for light surfaces.
- Use `initial` to tell the components to use its default behavior.

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

render(
  <Section surface="dark">
    Children will use the dark surface behavior (ondark).
    <Theme.Context surface="initial">
      Children will use their default surface behavior
    </Theme.Context>
  </Section>
)
```

### Use your component as the wrapper element

You can provide your component as the wrapper. This way no additional HTML Element will be created.

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

const Component = ({ className ...props }) => {
  return <div className={className+' more-classes'} {...props} />
}

render(
  <Theme name="theme-name">
    <App>
      <Theme name="sbanken" element={Component}>
        ...
      </Theme>
    </App>
  </Theme>
)
```

### Hide or show parts of your component (filter)

With this helper function you show or hide content based on inherited theme properties.

```tsx
import { Theme, VisibilityByTheme } from '@dnb/eufemia/shared'

render(
  <Theme name="...">
    Only shown in Sbanken theme Only hidden in Eiendom theme Only shown in
    Sbanken or Eiendom theme Only shown in Sbanken or Eiendom theme Only
    shown in Sbanken then or Eiendom theme – that also includes the fictive
    variant="blue".
  </Theme>
)
```

### Integrations

By using the [gatsby-plugin-eufemia-theme-handler](https://github.com/dnbexperience/gatsby-plugin-eufemia-theme-handler) plugin, your app will get wrapped with this theme component.

## Properties

```json
{
  "props": {
    "name": {
      "doc": "The name of a branding theme. Can be `ui` (universal identity), `eiendom`, `sbanken` or `carnegie`.",
      "type": ["\"ui\"", "\"eiendom\"", "\"sbanken\"", "\"carnegie\""],
      "status": "optional"
    },
    "size": {
      "doc": "Will define what sizes of components are used (WIP).",
      "type": "\"basis\"",
      "status": "optional"
    },
    "variant": {
      "doc": "(WIP).",
      "type": "string",
      "status": "optional"
    },
    "contrastMode": {
      "doc": "When a component supports a contrast style, it will be used instead for the dedicated area.",
      "type": "boolean",
      "status": "optional"
    },
    "colorScheme": {
      "doc": "Controls the color scheme. Use `auto` to follow system preference and switch automatically between light and dark, `light` for light mode, `dark` for dark mode, or `inherit` to inherit from a parent Theme. Defaults to `undefined`.",
      "type": ["\"auto\"", "\"light\"", "\"dark\"", "\"inherit\""],
      "status": "optional"
    },
    "surface": {
      "doc": "Adjusts component appearance based on background. Use `dark` when content is placed on a dark surface, `light` for light, or `initial` to reset to the component's default behavior, ignoring any parent surface context. Defaults to `undefined`.",
      "type": ["\"dark\"", "\"light\"", "\"initial\""],
      "status": "optional"
    }
  }
}
```