ThemeProvider

The ThemeProvider is a context that persists user theme preferences and syncs with the system’s light/dark setting. It provides a useTheme hook to manage theme state at runtime and sets data attributes on the <html> element.

Simple setup

Wrap your app with ThemeProvider and pass the style configuration as props.

layout.tsx

<ThemeProvider
  theme="system" // system | dark | light
  brand="blue" // blue | indigo | violet | magenta | pink | red | orange | yellow | moss | green | emerald | aqua | cyan
  accent="indigo" // blue | indigo | violet | magenta | pink | red | orange | yellow | moss | green | emerald | aqua | cyan
  neutral="gray" // sand | gray | slate
  solid="contrast" // color | contrast
  solidStyle="flat" // flat | plastic
  border="playful" // rounded | playful | conservative
  surface="translucent" // filled | translucent
  transition="all" // all | micro | macro
  scaling="100" // 90 | 95 | 100 | 105 | 110
>
  {children}
</ThemeProvider>

Advanced setup

You can create a single source of truth for all style configuration in a separate file, for example once-ui.config.js. We also recommend using a Providers component to wrap your app.

import { style } from "@/resources/once-ui.config";
import { ThemeProvider, DataThemeProvider, IconProvider, BorderStyle, ToastProvider, NeutralColor, ScalingSize, Schemes, SolidStyle, SolidType, SurfaceStyle, TransitionStyle, Theme } from "@once-ui-system/core";

export function Providers({ children }: {
  children: React.ReactNode
}) {
  return (
    <ThemeProvider
      theme={style.theme as Theme}
      brand={style.brand as Schemes}
      accent={style.accent as Schemes}
      neutral={style.neutral as NeutralColor}
      solid={style.solid as SolidType}
      solidStyle={style.solidStyle as SolidStyle}
      border={style.border as BorderStyle}
      surface={style.surface as SurfaceStyle}
      transition={style.transition as TransitionStyle}
      scaling={style.scaling as ScalingSize}>
      <DataThemeProvider>
        <ToastProvider>
          <IconProvider>
            {children}
          </IconProvider>
        </ToastProvider>
      </DataThemeProvider>
    </ThemeProvider>
  );
}

If you don't pass any props to the ThemeProvider, it will fall back to defaults. If the visitor has theme preferences (saved in localStorage), the ThemeProvider will use those. To force a theme, set theme on the ThemeProvider as light or dark.

Custom color

Use a custom color palette for the data-brand, data-accent and data-neutral attributes by setting their values to custom and loading the CSS variables in the layout.tsx file. You can generate palettes using the Once UI customize page.

:root {
--scheme-brand-100: #08002f;
--scheme-brand-200: #04025c;
--scheme-brand-300: #1f398e;
--scheme-brand-400: #3856ae;
--scheme-brand-500: #5071cc;
--scheme-brand-600: #6f94f1;
--scheme-brand-700: #8db3ff;
--scheme-brand-800: #b2dbff;
--scheme-brand-900: #bfe8ff;
--scheme-brand-1000: #ccf6ff;
--scheme-brand-1100: #d2fcff;
--scheme-brand-1200: #d2fcff;
--scheme-brand-600-15: rgba(111,148,241,0.15);
--scheme-brand-600-30: rgba(111,148,241,0.3);
--scheme-brand-600-50: rgba(111,148,241,0.5);

  --scheme-accent-100:  #030b10;
  --scheme-accent-200:  #0d181d;
  --scheme-accent-300:  #364248;
  --scheme-accent-400:  #505d64;
  --scheme-accent-500:  #69777e;
  --scheme-accent-600:  #8a989f;
  --scheme-accent-700:  #a8b7bf;
  --scheme-accent-800:  #c8d7df;
  --scheme-accent-900:  #d5e4ec;
  --scheme-accent-1000: #e2f1f9;
  --scheme-accent-1100: #e9f8ff;
  --scheme-accent-1200: #efffff;
  --scheme-accent-600-15: rgba(138,152,159,0.15);
  --scheme-accent-600-30: rgba(138,152,159,0.3);
  --scheme-accent-600-50: rgba(138,152,159,0.5);

  --scheme-neutral-100:  #020b10;
  --scheme-neutral-200:  #0b181d;
  --scheme-neutral-300:  #344248;
  --scheme-neutral-400:  #4f5d64;
  --scheme-neutral-500:  #68777e;
  --scheme-neutral-600:  #89989f;
  --scheme-neutral-700:  #a7b7be;
  --scheme-neutral-800:  #c7d7df;
  --scheme-neutral-900:  #d4e4ec;
  --scheme-neutral-1000: #e1f2f9;
  --scheme-neutral-1100: #e7f8ff;
  --scheme-neutral-1200: #eeffff;
  --scheme-neutral-600-15: rgba(137,152,159,0.15);
  --scheme-neutral-600-30: rgba(137,152,159,0.3);
  --scheme-neutral-600-50: rgba(137,152,159,0.5);

}

UseTheme

Access and modify theme state with useTheme:

useTheme

const { theme, setTheme } = useTheme();

useEffect(() => {
console.log("Current theme:", theme);
}, [theme]);

SSR hydration

Add the <ThemeInit> component to the <head> to set the initial theme before hydration in layout.tsx. It will prevent flash of unstyled content (FOUC).

layout.tsx

<head>
  <ThemeInit
    config={{
      theme: style.theme,
      brand: style.brand,
      accent: style.accent,
      neutral: style.neutral,
      solid: style.solid,
      'solid-style': style.solidStyle,
      border: style.border,
      surface: style.surface,
      transition: style.transition,
      scaling: style.scaling,
      'viz-style': dataStyle.variant,
    }}
  />
</head>

Style your app

Visit the ThemeSwitcher or StylePanel page for native, out-of-the-box ThemeProvider implementation with localStorage persistence. Use these components to provide user-facing style controls or to quickly test different styles during development.

PageCustomize page theme

Theme

Shape

ColorCustomize color schemes

Brand

Accent

Neutral

Solid styleCustomize the appearance of interactive elements

Style

Effect

AdvancedCustomize advanced styling options

Surface

Scaling

Data Style

Transition

Style overrides

The ThemeProvider relies on data attributes to set theme and style preferences. Data modes are inherited from the parent and can be applied to any semantic HTML element, providing simple, seamless style overrides. Just add the data-theme, data-neutral, data-brand, data-accent, data-border, data-surface, data-solid, data-solid-style, data-transition or data-scaling attributes to any semantic HTML element to override its default style.

Persistence

Style choices are mirrored into localStorage under data-<kebab-key>. Set persistence to change that:

"local" — the default described above.
"none" — choices apply to the document but are not stored. Use this when a host owns the state, such as an editor holding an unsaved draft.
an adapter — route persistence somewhere else, such as a database.

Tsx

<ThemeProvider
  brand={site.brand}
  persistence={{
    set: (key, value) => saveSiteStyle(site.id, key, value),
  }}
>

get runs during hydration, so it must be synchronous — an await there would show a flash of the wrong theme. When the values live somewhere async, omit get and seed the provider through its props from the server instead. set and remove may return a promise; nothing waits on them.

API reference

Prop	Type	Default
children	React.ReactNode	—
theme	systemdarklight	system
brand	blueindigovioletmagentapinkredorangeyellowmossgreenemeraldaquacyancustom	blue
accent	blueindigovioletmagentapinkredorangeyellowmossgreenemeraldaquacyancustom	indigo
neutral	sandgrayslatecustom	gray
solid	colorcontrastinverse	contrast
solidStyle	flatplastic	flat
border	roundedplayfulconservative	playful
surface	filledtranslucent	translucent
transition	allmicromacronone	all
scaling	9095100105110	100

useTheme

Returns { theme, resolvedTheme, setTheme }.

Prop	Type	Default
theme Current theme setting	Theme	—
resolvedTheme Actual resolved theme	"light" \| "dark"	—
setTheme Update theme	(theme: Theme) => void	—

useStyle

Returns all style options plus setStyle.

Prop	Type	Default
theme	Theme	—
neutral	NeutralColor \| "custom"	—
brand	Schemes \| "custom"	—
accent	Schemes \| "custom"	—
solid	SolidType	—
solidStyle	SolidStyle	—
border	BorderStyle	—
surface	SurfaceStyle	—
transition	TransitionStyle	—
scaling	ScalingSize	—
setStyle	(style: Partial<StyleOptions>) => void	—

Overrides

Lorant

Launch your fully functional ecommerce store in an hourWith the power of Fourthwall and flexibility of Once UI.

Because you follow

Productivity

Jun 23

Lorant

Ship quality product docs without writing codeMagic Docs is Once UI's mdx-based documentation template.

Because you follow

Design

Jun 16

<Column
  data-theme="dark"
  data-border="playful">
  <Row
    data-theme="light"
    data-border="rounded">
    {children}
  </Row>
  <Row>
    {children}
  </Row>
</Column>