Quick Start

Install the packages

Install Vortex and the build dependencies used by its PostCSS preset.

bun add @vortexlabs/vortex

bun add -d postcss @csstools/postcss-global-data postcss-custom-media cssnano

Generate your theme

Create vortex.config.ts at your project root. Replace acme with your theme name; an empty definition inherits Vortex's defaults.

import type { VortexThemeConfig } from "@vortexlabs/vortex";

const config: VortexThemeConfig = {
themes: {
  acme: {},
},
};

export default config;

Add a script to your existing package.json. The CLI is included in @vortexlabs/vortex.

"scripts": {
"build:theme": "vortex theming --output ./src/themes"
}

bun run build:theme

This creates src/themes/acme/. Run the script again after changing vortex.config.ts, before starting or building your app. See Create a Theme to customize your tokens.

Configure PostCSS

Create this file at your project root. The preset loads Vortex's default breakpoint definitions and converts its custom media queries into browser-compatible CSS.

const { config } = require("@vortexlabs/vortex/config/postcss");

module.exports = config;

If you already have a PostCSS config, merge config.plugins into its plugins object instead of replacing the existing configuration. Restart your dev server after changing it.

If you customize breakpoints, follow Custom breakpoints to use your generated definitions.

Import the theme

Import the generated theme once in your app's root entry or layout. For an entry at src/main.tsx:

import "./themes/acme/globals.css";

This includes the theme tokens and typography. You don't need separate imports for typography.css or breakpoints.css; the PostCSS preset reads the breakpoints file.

Add the provider

Wrap your application with VortexProvider to set the theme and color mode and enable shared component behavior.

import { VortexProvider } from "@vortexlabs/vortex";
import type { ReactNode } from "react";

export function Providers({ children }: { children: ReactNode }) {
return (
  <VortexProvider defaultTheme="acme" defaultColorMode="light">
    {children}
  </VortexProvider>
);
}

Render your app inside <Providers>. For Next.js client boundaries or server-rendered theme attributes, use the framework guide above.

Use a component

Render this component inside the provider. It uses only the Vortex package installed above.

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

export default function Example() {
return (
  <Stack gap={4} direction={{ xs: "column", sm: "row" }}>
    <Button variant="primary">Get started</Button>
    <Button variant="secondary">Learn more</Button>
  </Stack>
);
}