8
Hooks

useTheme

A hook that provides theme management with system preference detection and localStorage persistence.

useTheme

The useTheme hook provides theme management functionality with features like system preference detection and localStorage persistence. It allows users to easily switch between light, dark, and system themes in your application.

Current theme: system

Installation

Install the useTheme hook using:

npx axionjs-ui add hook use-theme

Provider Setup

You need to wrap your application with the ThemeProvider to use the useTheme hook:

// In your layout.tsx
import { ThemeProvider } from "@/hooks/use-theme";
 
export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head />
      <body>
        <ThemeProvider defaultTheme="system" storageKey="ui-theme">
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

File Structure

use-theme.ts

ThemeProvider Props

PropTypeDefault
children
React.ReactNode
Required
defaultTheme
"light" | "dark" | "system"
"system"
storageKey
string
"theme"

useTheme Return Value

PropTypeDefault
theme
"light" | "dark" | "system"
-
setTheme
(theme: 'light' | 'dark' | 'system') => void
-

Examples

Theme Switcher with Buttons

A simple theme switcher with separate buttons for each theme option.

Current theme: system

Theme Toggle

A simple toggle switch between light and dark mode.

import { useTheme } from "@/hooks/use-theme";
import { Switch } from "@/components/ui/switch";
import { Sun, Moon } from "lucide-react";
 
function ThemeToggle() {
  const { theme, setTheme } = useTheme();
  const isDark = theme === "dark" || 
    (theme === "system" && window.matchMedia("(prefers-color-scheme: dark)").matches);
  
  const handleToggle = (checked: boolean) => {
    setTheme(checked ? "dark" : "light");
  };
  
  return (
    <div className="flex items-center gap-2">
      <Sun className="h-4 w-4" />
      <Switch 
        checked={isDark}
        onCheckedChange={handleToggle}
      />
      <Moon className="h-4 w-4" />
    </div>
  );
}

Use Cases

  • Website Theming: Implement light and dark modes for your website
  • User Preferences: Respect user’s system preferences while allowing manual override
  • Accessibility: Support users who prefer specific contrast levels
  • Reading Modes: Implement reading-friendly themes for content-heavy sites
  • Branded Experiences: Create themed experiences for different sections of your app

Accessibility

The useTheme hook enhances accessibility by:

  • Supporting system preferences for users who have set their OS to dark or light mode
  • Persisting theme choices for returning users
  • Allowing users to select their preferred theme for better reading comfort
  • Supporting reduced motion preferences when combined with appropriate CSS

Best Practices

  • Include the ThemeProvider at the root of your application
  • Use CSS variables for theme colors to ensure consistent theming
  • Add the suppressHydrationWarning attribute to the html element to avoid hydration warnings
  • Consider offering a high contrast theme option for users with visual impairments
  • Use semantic color names in your CSS variables (e.g., --background, --foreground) rather than light/

Previous

useSseListener

Next

useToggle

On this page