Skip to main content

Vortex Provider

Vortex Provider is a root wrapper that sets up Vortex for your app, such as its theme, color mode, and reading direction.

Import

import { VortexProvider } from '@vortexlabs/vortex';
import type { VortexProviderProps } from '@vortexlabs/vortex';

Allied components

Other links

Content inside the provider uses the Vortex theme.
"use client";

import "@vortexlabs/vortex-themes/themes/vortex/theme.css";

import { Button, Stack, Text, VortexProvider } from "@vortexlabs/vortex";

export const ProviderUsage = () => {
  return (
    <VortexProvider defaultTheme="vortex" defaultColorMode="light" scoped>
      <Stack backgroundColor="surface-subtlest" padding={5} gap={3} borderRadius="md">
        <Text>Content inside the provider uses the Vortex theme.</Text>
        <Button>Get started</Button>
      </Stack>
    </VortexProvider>
  );
};

Features

  • Supports themes and theme overrides.
  • Supports light, dark, and system color mode preferences.
  • Supports scoping to embedded apps.
  • Supports useToast, with per-position defaults.
  • Supports useShortcuts and keyboard focus rings.
  • Supports right-to-left layouts and a fallback breakpoint.

Wrap your app at its root, after importing your generated theme CSS; Quick Start covers the full setup. This preview uses scoped to stay local. className and attributes go on a display: contents wrapper, so they don't affect layout.

Themes

Set defaultTheme to a theme name, or to an array like ["sleek", "astra"] to add overrides. Load the CSS for each one.

<VortexProvider defaultTheme={["sleek", "astra"]}>
  {children}
</VortexProvider>

Set theme instead when your app stores the selection; useTheme can't change it.

System Color Mode

Set defaultColorMode="system" to follow the OS. Choosing light or dark stops following it.

<VortexProvider defaultColorMode="system">
  {children}
</VortexProvider>

Use onColorModePreferenceChange to save the preference, including "system"; onColorModeChange receives resolved light or dark requests. Automatic OS changes don't call either handler.

Controlled Color Mode

Set colorMode when your app stores the setting. Update it in onColorModeChange, or useTheme can't change it.

Controlled mode: light
"use client";

import "@vortexlabs/vortex-themes/themes/vortex/theme.css";

import { Button, Stack, Text, VortexProvider, useTheme } from "@vortexlabs/vortex";
import React from "react";

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

export const ProviderControlled = () => {
  const [mode, setMode] = React.useState<"light" | "dark">("light");
  return (
    <VortexProvider scoped colorMode={mode} onColorModeChange={setMode}>
      <Stack backgroundColor="surface-subtlest" padding={5} gap={3} borderRadius="md">
        <Text>Controlled mode: {mode}</Text>
        <ModeButton />
      </Stack>
    </VortexProvider>
  );
};

Embedded Content

Set scoped to keep theme and color mode inside the provider, like when Vortex runs inside another app. Without defaultColorMode, a scoped provider inherits its parent's preference, including "system". An unscoped nested provider shares its parent's color mode and ignores defaultColorMode. For local theme tokens only, use ThemeScope.

Light embedded app
Dark embedded app
"use client";

import "@vortexlabs/vortex-themes/themes/vortex/theme.css";

import { Button, Stack, Text, VortexProvider } from "@vortexlabs/vortex";

export const ProviderScoped = () => {
  return (
    <Stack direction={{ xs: "column", sm: "row" }} gap={4}>
      <VortexProvider scoped defaultColorMode="light">
        <Stack backgroundColor="surface-subtlest" padding={5} gap={3}>
          <Text>Light embedded app</Text>
          <Button>Light action</Button>
        </Stack>
      </VortexProvider>
      <VortexProvider scoped defaultColorMode="dark">
        <Stack backgroundColor="surface-subtlest" padding={5} gap={3}>
          <Text>Dark embedded app</Text>
          <Button>Dark action</Button>
        </Stack>
      </VortexProvider>
    </Stack>
  );
};

Toast Defaults

Any component inside the provider can call useToast. toastOptions sets each position's width and expanded state; Toast shows how.

Direction and Responsive Fallback

defaultRTL starts the whole page right-to-left, even with scoped; useRTL changes it later.

defaultBreakpoint is what JavaScript responsive utilities use before the viewport is measured, like during server rendering. CSS breakpoints don't change.

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

<VortexProvider defaultRTL defaultBreakpoint="xs">
  <Text>مرحبًا بك</Text>
</VortexProvider>

Server Rendering

In your server HTML, set the theme and color-mode attributes on <html> to match the root provider, and load the CSS for every theme you'll select. The provider doesn't generate CSS or save preferences; the Next.js guide shows a full setup.

For "system", see Color Modes.

Accessibility

Description
Shows focus rings after keyboard input and hides them after a mouse click.
Doesn't add accessible names or semantics; each control still needs its own.