Dark Mode

Add light and dark mode to your app.

Appica UI is dark-mode-ready out of the box. The token system ships both a light and a dark palette; switching themes is a matter of toggling a class on the <html> element, which ThemeProvider manages for you - including persistence and a no-flash first paint.

How it works

Dark mode is class-based. When the dark class is on a <html> ancestor, the dark token values apply. The library defines the variant as:

@custom-variant dark (&:is(.dark *));

So you can write dark-only utilities in your own markup too:

<div className="bg-background text-foreground dark:shadow-xl">…</div>

Setup

Wrap your app in ThemeProvider at your app's root (covered in Installation). It applies the correct class before the page paints, so there's no flash of the wrong theme on load. The example uses Next.js's root layout - see the Framework notes for where this file lives in Vite, React Router / Remix, TanStack Start, and Astro:

app/layout.tsx (Next.js)

import { ThemeProvider } from '@appica/ui-react/providers/theme-provider'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  )
}

suppressHydrationWarning on <html> is expected: the no-flash script sets the theme class before React hydrates, so the server and client markup intentionally differ by that one attribute.

By default ThemeProvider follows the OS preference (enableSystem) and persists the user's choice under the theme key in localStorage.

Building a theme toggle

Read and set the theme with useTheme. Guard theme-dependent UI with mounted so the server-rendered output matches the first client render:

theme-toggle.tsx

'use client'

import { useTheme } from '@appica/ui-react/hooks/use-theme'
import { Button } from '@appica/ui-react/button'
import { SunHigh, MoonStars } from '@appica/icons-react'

export function ThemeToggle() {
  const { resolvedTheme, setTheme, mounted } = useTheme()

  // Avoid rendering theme-specific content until mounted.
  if (!mounted) return <Button variant="ghost" size="icon-md" aria-label="Toggle theme" />

  const next = resolvedTheme === 'dark' ? 'light' : 'dark'
  return (
    <Button variant="ghost" size="icon-md" aria-label="Toggle theme" onClick={() => setTheme(next)}>
      {resolvedTheme === 'dark' ? <MoonStars /> : <SunHigh />}
    </Button>
  )
}

theme is the stored choice, which may be 'system'.
resolvedTheme is what's actually applied - 'system' resolved to 'light' or 'dark'.
systemTheme is the current OS preference.

Common options

ThemeProvider accepts several props to tune behavior:

Prop	Default	Description
`defaultTheme`	`'system'` (if `enableSystem`)	Theme used before the user makes a choice
`enableSystem`	`true`	Follow the OS `prefers-color-scheme`
`storageKey`	`'theme'`	`localStorage` key for the persisted choice
`forcedTheme`	-	Pin a theme for a subtree (e.g. a marketing page)
`disableTransitionOnChange`	`false`	Suppress CSS transitions during the switch
`enableColorScheme`	`true`	Set `color-scheme` so native controls match

forcedTheme pins the whole app, so it belongs on the provider that owns the state:

<ThemeProvider forcedTheme="dark">
  <App />
</ThemeProvider>

Nested providers are a no-op

Only the outermost ThemeProvider owns the theme. A second one further down the tree returns its children untouched, so wrapping a route in <ThemeProvider forcedTheme="dark"> under an app-root provider changes nothing and reports no error. To theme part of a page, use the dark class as below.

Scoped dark regions and portals

To make one region dark inside an otherwise light page, put the class on a wrapper. The variant is a descendant selector, and .dark sets the token custom properties, which inherit - so everything underneath flips:

<div className="dark bg-background text-foreground">
  <Sidebar />
</div>

Anything that opens a popup from inside that region is the exception. Select, DropdownMenu, Tooltip, Dialog and friends portal their popup to <body>, which lands it outside your wrapper, so it renders in the page's theme rather than the region's.

React context isn't the problem. createPortal keeps the node in the React tree, so context crosses it fine. Only CSS inheritance breaks, because the popup's DOM parent is <body>.

That makes the fix small: the class only has to reach some ancestor of the popup, and every *Content exposes one.

<SelectContent positionerProps={{ className: 'dark' }} />
<DropdownMenuContent positionerProps={{ className: 'dark' }} />
<TooltipContent positionerProps={{ className: 'dark' }} />
<DrawerContent viewportProps={{ className: 'dark' }} />

Floating components take positionerProps: Select, DropdownMenu, Tooltip, Popover, Combobox, Autocomplete, ContextMenu, Menubar, PreviewCard.
Modal components take viewportProps: Dialog, AlertDialog, Drawer.

Both merge your className with their own, so the class is added rather than replacing anything.

Why not `container`

Every one of these components also has a flat container prop that moves the portal target, and pointing it at your dark wrapper looks like the tidier fix. It isn't, for three reasons:

Clipping comes back. Portaling to <body> is what lets a popup escape an ancestor's overflow: hidden. Aim it at a rounded panel and you get the clipping back.
Stacking changes. Popups are z-50, which inside a container is relative to that container's stacking context rather than the page.
It breaks Dialog and Drawer outright. Their backdrop and viewport are position: fixed. Any ancestor with transform, filter, backdrop-filter, contain or will-change becomes the containing block, and the full-screen overlay collapses to that container's box. These surfaces use backdrop-blur and Motion writes transforms, so the trigger is common rather than exotic.

container has a real purpose - shadow DOM, an iframe, a deliberate stacking context - covered in Composition. Theming isn't it.

`resolvedTheme` reports the global theme

useTheme().resolvedTheme reads the provider, not the region a component sits in, so inside a scoped .dark wrapper it still returns the page's theme. Styling is unaffected, since that runs on CSS. Anything that branches in JavaScript on the theme - a chart palette, a theme-specific image - will pick the wrong one there, so pass the region's theme down explicitly instead.

See ThemeProvider for the full prop reference and useTheme for the hook.

Getting Started

Guides

Utilities

Dark Mode

How it works

Setup

Building a theme toggle

Common options

Nested providers are a no-op

Scoped dark regions and portals

Why not `container`

`resolvedTheme` reports the global theme

Dark Mode

How it works

Setup

Building a theme toggle

Common options

Nested providers are a no-op

Scoped dark regions and portals

Why not container

`resolvedTheme` reports the global theme

Why not `container`