Quick Start

Install the packages

Vortex packages are private and available by invitation. Before installing, accept your package-access invitation and authenticate your package manager with the npm account that received access. See the package access terms.

Install Vortex, its required Vortex Themes peer dependency, and the build dependencies used by its PostCSS preset.

bun add @vortexlabs/vortex @vortexlabs/vortex-themes

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

For TypeScript projects, align the React types with React 19:

bun add -d @types/react@^19 @types/react-dom@^19

When upgrading Vortex, review the release notes for breaking changes and compatibility requirements.

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-themes";

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

export default config;

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

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

bun run build:theme

This creates src/themes/acme/. Run the script again after changing vortex.config.ts or upgrading Vortex or Vortex Themes, before starting or building your app.

Configure PostCSS

Create this file at your project root. The preset loads Vortex's default breakpoints and compiles its custom media queries.

import { config } from "@vortexlabs/vortex/config/postcss";

export default config;

If you already have a PostCSS config, merge config.plugins into it. Restart your dev server after changing it.

If you customize breakpoints, configure PostCSS 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 React from "react";

type Props = {
  children: React.ReactNode;
};

export const Providers = (props: Props) => {
  const { children } = props;

  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";

const Example = () => {
  return (
    <Stack gap={4} direction={{ xs: "column", sm: "row" }}>
      <Button variant="primary">Get started</Button>
      <Button variant="secondary">Explore Vortex</Button>
    </Stack>
  );
};

export default Example;