Color Modes

Every theme defines light and dark colors through the light and dark values in its semantic color tokens. Changing the color mode keeps the selected theme.

Set the initial mode

After loading your theme, set defaultColorMode on VortexProvider:

import { VortexProvider } from "@vortexlabs/vortex";

<VortexProvider defaultTheme="acme" defaultColorMode="dark">
  {children}
</VortexProvider>

defaultColorMode sets the initial state. Without it, a provider uses its parent's mode or "light" at the app root.

Vortex doesn't follow the system setting. To match it, read prefers-color-scheme and pass the result as defaultColorMode or colorMode.

Switch modes

Render this toggle inside your provider:

"use client";

import { Button, useTheme } from "@vortexlabs/vortex";

export const ColorModeToggle = () => {
  const { colorMode, invertColorMode } = useTheme();

  return (
    <Button onClick={invertColorMode}>
      {colorMode === "light" ? "Use dark mode" : "Use light mode"}
    </Button>
  );
};

Use setColorMode("light") or setColorMode("dark") from the same hook to select a specific mode. These setters change the mode for the whole provider, even when called inside a ThemeScope. To keep one section dark or inverted, use Scoped Theming.

Tailwind CSS semantic color utilities follow the mode; use dark: only for extra changes.

Control and remember the mode

If your app owns the preference, pass colorMode and handle change requests through onColorModeChange:

<VortexProvider
  defaultTheme="acme"
  colorMode={colorMode}
  onColorModeChange={setColorMode}
>
  {children}
</VortexProvider>

Here, colorMode and setColorMode are your app's state and setter. Save changes in a cookie or user setting if they should survive a reload; Vortex does not persist them automatically.

For server rendering, pass the saved preference to both the provider and <html data-vortex-color-mode>, falling back to a default for values other than "light" or "dark". See the Next.js guide for the root layout.