Scoped Theming

Apply a theme override to one part of your page.

Create an override

For a small change, create a themeOverride instead of a full theme. This example, astra, gives primary buttons an orange brand color while keeping the rest of your theme.

Add it alongside themes in vortex.config.ts:

vortex.config.ts

themeOverride: {
  astra: {
    globalTokens: {
      color: {
        brandPrimary500: { color: "oklch(58.4% 0.203 35.344)" },
        brandPrimary600: { color: "oklch(52% 0.18 35.344)" },
      },
    },
    semanticTokens: {
      color: {
        backgroundButtonPrimaryDefault: { lightMode: "brandPrimary500", darkMode: "brandPrimary500" },
        backgroundButtonPrimaryHover: { lightMode: "brandPrimary600", darkMode: "brandPrimary600" },
        borderButtonPrimaryDefault: { lightMode: "brandPrimary500", darkMode: "brandPrimary500" },
        borderButtonPrimaryHover: { lightMode: "brandPrimary600", darkMode: "brandPrimary600" },
      },
    },
  },
},

Run bun run build:theme, then import the override after the base theme:

src/main.tsx

import "./themes/sleek/globals.css";
import "./themes/overrides/astra/theme.css";

CSS import order determines precedence when matching declarations have equal specificity. The order of theme names in an array doesn't change that order.

Apply it to part of the page

Use ThemeScope inside your VortexProvider, and pass the base theme with the override:

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

export const App = () => {
  return (
    <VortexProvider defaultTheme="sleek">
      <Button>Sleek button</Button>
      <ThemeScope name={["sleek", "astra"]}>
        <Button>Astra button</Button>
      </ThemeScope>
    </VortexProvider>
  );
};

Only content inside the scope uses astra. The rest of the page keeps sleek, and both use the parent's color mode. To use the override everywhere, pass defaultTheme={["sleek", "astra"]} to your provider.

Scope the color mode

Set a fixed color mode or invert the parent's mode while keeping its theme:

<ThemeScope colorMode="dark">
  <Button>Always dark</Button>
</ThemeScope>

<ThemeScope colorMode="inverted">
  <Button>Opposite color mode</Button>
</ThemeScope>

ThemeScope applies tokens without adding a layout box. Put a layout component inside it when you need a background or spacing.

See Create Theme to define the theme tokens used by your scopes.