useTheme

Read and set the active theme.

useTheme reads and sets the active theme. It returns the stored choice, the resolved theme, the OS preference, and a setter — everything you need to build a theme switcher.

import { useTheme } from '@appica/ui-react/hooks/use-theme'

Usage

Guard theme-dependent UI with mounted so the first client render matches the server output and you avoid a hydration mismatch:

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>
  )
}

Return value

Property	Type	Description
`theme`	`string \| undefined`	The stored choice, possibly `'system'`
`setTheme`	`(value: string \| ((prev: string) => string)) => void`	Set the theme; persisted automatically
`resolvedTheme`	`string \| undefined`	What's actually applied — `'system'` resolved
`systemTheme`	`'light' \| 'dark' \| undefined`	The current OS preference
`themes`	`string[]`	Available theme names
`forcedTheme`	`string \| undefined`	The forced theme, if a provider pinned one
`mounted`	`boolean`	`false` until the client mounts — guard themed UI

Requires a ThemeProvider ancestor. Without one, the hook returns inert values (mounted stays false) rather than throwing.

Getting Started

For AI Agents

Guides

Utilities

useTheme

Usage

Return value