Theming

Twenty UI components read public CSS custom properties prefixed with --t-. Prefer semantic tokens such as background.secondary and font.color.primary when styling your own components; these values adapt to the active palette.

Use tokens in styles

themeCssVariables maps token paths to CSS variable references. Use it for values that CSS resolves:

import { themeCssVariables } from 'twenty-ui/theme';

export const Summary = () => (
  <section
    style={{
      background: themeCssVariables.background.secondary,
      color: themeCssVariables.font.color.primary,
      padding: themeCssVariables.spacing[4],
      borderRadius: themeCssVariables.border.radius.md,
    }}
  >
    Three tasks are due today.
  </section>
);

The equivalent CSS uses variables directly:

.summary {
  background: var(--t-background-secondary);
  color: var(--t-font-color-primary);
  padding: var(--t-spacing-4);
  border-radius: var(--t-border-radius-md);
}

Read resolved values

useTheme() reads the active provider’s computed tokens. Use it when a component expects a JavaScript number, such as an icon size. The provider needs the theme stylesheet to be loaded in the browser to resolve CSS variables.

import { IconCheck } from 'twenty-ui/icon';
import { useTheme } from 'twenty-ui/theme';

export const CompleteIcon = () => {
  const theme = useTheme();

  return <IconCheck size={theme.icon.size.md} aria-hidden />;
};

Every entry in themeCssVariables is a CSS reference string, including numeric tokens. Do not perform arithmetic on those strings. On the server, resolved browser values are unavailable; see Server rendering.

Scope an override

Pass applyToRoot={false} to apply a theme to a subtree. Override public CSS variables by their full name:

import { type ReactNode } from 'react';
import { ThemeProvider } from 'twenty-ui/theme';

export const EmbeddedPanel = ({ children }: { children: ReactNode }) => (
  <ThemeProvider
    colorScheme="light"
    applyToRoot={false}
    overrides={{ '--t-background-secondary': '#f4f6ff' }}
  >
    {children}
  </ThemeProvider>
);

A scoped provider adds a wrapper with display: contents; it does not create a layout box. It also supplies a container for components that support themed portals. Portals created by other libraries need their own container configuration. Variables prefixed with --tw- are private component details. Use public props and --t- tokens instead of depending on those variables. See the token reference for the available names and palette values.

Explicit values and scale

The theme prop supplies resolved JavaScript theme values instead of reading computed styles. It also flows to nested providers unless they supply another explicit theme. This changes values read by hooks; load the appropriate stylesheet and use CSS overrides to style components. scale writes --t-scale-user on the document root. It only affects interfaces whose CSS consumes that variable and is ignored by scoped providers. className applies to a scoped wrapper; passing it alone does not create a wrapper. overrides creates a scope even when applyToRoot remains true.

ThemeProvider props

boolean

default:"true"

Applies the color-scheme class to the document root. Set false for a scoped wrapper.

ReactNode

required

Components that share this theme.

string

Class applied to a scoped wrapper; no wrapper is created for className alone.

"dark" | "light"

required

Explicit light or dark palette; load its stylesheet before rendering.

ThemeOverrides

CSS custom-property overrides. Supplying them creates a scoped wrapper.

number

Root interface scale stored in —t-scale-user. Ignored for scoped providers; application CSS must consume the variable.

ThemeType | typeof THEME_LIGHT

Explicit resolved theme values, bypassing computed-style token resolution.

Overview

Apps

API

Self-Host

Contribute

UI Library

Use tokens in styles

Read resolved values

Scope an override

Explicit values and scale

ThemeProvider props

​Use tokens in styles

​Read resolved values

​Scope an override

​Explicit values and scale

​ThemeProvider props

Use tokens in styles

Read resolved values

Scope an override

Explicit values and scale

ThemeProvider props