React Setup

Complete setup guide for using Primus UI in a React application — including @primus/ui-core as the base design system.

1. Install packages

npm install primus-react-ui @primus/ui-core

2. Import styles

In your root main.tsx or index.tsx, import @primus/ui-core first, then the React SDK styles:

// main.tsx
import '@primus/ui-core/dist/primus-ui.min.css'; // base design system
import 'primus-react-ui/styles.css';              // React SDK overrides
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(<App />);

3. Add the theme bridge

Wrap your app with PrimusThemeProvider and place <PrimusUiCoreBridge /> once at the root. This ensures the Primus purple brand palette is applied to both React components and any plain HTML elements styled by @primus/ui-core.

// App.tsx
import { PrimusThemeProvider, PrimusUiCoreBridge } from 'primus-react-ui';

export default function App() {
  return (
    <PrimusThemeProvider defaultTheme="dark">
      <PrimusUiCoreBridge /> {/* syncs theme → @primus/ui-core CSS tokens */}
      <YourRoutes />
    </PrimusThemeProvider>
  );
}

Or use the hook directly in your root layout component:

import { usePrimusUiCoreBridge } from 'primus-react-ui';

function RootLayout({ children }: { children: React.ReactNode }) {
  usePrimusUiCoreBridge(); // call once — no render output
  return <>{children}</>;
}

4. Wrap with PrimusProvider (broker auth)

import { PrimusProvider, PrimusThemeProvider, PrimusUiCoreBridge, PrimusLogin, usePrimusAuth } from 'primus-react-ui';

function App() {
  return (
    <PrimusProvider authority="https://api.yourdomain.com" authBasePath="/api/auth" clientId="my-app">
      <PrimusThemeProvider defaultTheme="dark">
        <PrimusUiCoreBridge />
        <LoginPage />
      </PrimusThemeProvider>
    </PrimusProvider>
  );
}

function LoginPage() {
  const { login } = usePrimusAuth();
  return (
    <PrimusLogin
      showEmailLogin
      socialProviders={['azure', 'auth0', 'google']}
      onLogin={({ username, password }) => login({ email: username, password })}
    />
  );
}

If your backend exposes /auth/* instead of /api/auth/*, set authBasePath="/auth" and authEndpoint="/auth".

5. Use components

import { PrimusDataTable, PrimusModal, PrimusDashboard } from 'primus-react-ui';

// React SDK components
<PrimusDataTable columns={columns} data={rows} selectable />
<PrimusModal open={isOpen} title="Confirm" onClose={() => setIsOpen(false)}>
  Modal content
</PrimusModal>

// Plain HTML elements — styled by @primus/ui-core automatically
<button>Primary Action</button>
<button data-variant="secondary">Cancel</button>
<span class="badge success">Active</span>
<div class="card stat">
  <span class="card-label">MRR</span>
  <span class="card-value">$142k</span>
  <span class="card-delta up">+12%</span>
</div>

Theme switching

import { usePrimusTheme } from 'primus-react-ui';

function ThemeToggle() {
  const { theme, toggleTheme } = usePrimusTheme();
  return (
    <button onClick={toggleTheme}>
      Switch to {theme === 'dark' ? 'light' : 'dark'} mode
    </button>
  );
}

Calling toggleTheme() updates both React components and any @primus/ui-core styled HTML in one step.

What's available

Layer	Package	What it provides
Base design system	@primus/ui-core	Design tokens, semantic HTML styles, Web Components, toast API
React components	primus-react-ui	80+ React components for SaaS apps

See the component list for the full catalog, or the @primus/ui-core reference for the base layer.