Installation

Get started with Versa UI by following this installation guide. It covers everything you need to integrate Versa UI into your React project.

Prerequisites

Before installing Versa UI, ensure your project meets these requirements:

React 18.0 or higher (React 19 recommended)
Tailwind CSS 4.0 or higher
A bundler like Vite, Next.js, or Webpack

Versa UI is built with Tailwind CSS v4 and React 19. If you're using older versions, some components may not work as expected.

Package Installation

Install the Versa UI package:

npm install @versaui/ui/react

Core Dependencies

These packages are required by all components. Install any that your project doesn't already have:

npm install react react-dom tailwindcss clsx tailwind-merge class-variance-authority @phosphor-icons/react

Interaction & Accessibility Dependencies

Used by Button, Checkbox, Toggle, Slider, SegmentedControl, ProgressBar, and other interactive components:

npm install @react-aria/focus @react-aria/interactions @react-aria/button @react-aria/progress @react-aria/utils react-aria-components

The Dropdown component uses Floating UI for positioning:

npm install @floating-ui/react

Date & Calendar Dependencies

Required only if you use DatePicker, DateRangePicker, or Calendar components:

npm install @internationalized/date @react-aria/calendar @react-aria/i18n @react-stately/calendar @react-types/calendar @react-types/shared

CSS Setup

Import the required styles in your main CSS file. Order matters:

/* Fonts — all families used across themes */
@import url('https://fonts.googleapis.com/css2?family=DM+Mono:ital,wght@0,300;0,400;0,500;1,300;1,400;1,500&family=DM+Sans:ital,opsz,wght@0,9..40,100..1000;1,9..40,100..1000&family=DM+Serif+Display&family=Manrope:wght@200..800&family=Plus+Jakarta+Sans:ital,wght@0,200..800;1,200..800&family=Space+Grotesk:wght@300..700&display=swap');

/* Tailwind + Versa UI source scanning */
@import "tailwindcss";
@source "../node_modules/@versaui/ui/react/dist/**/*.{js,ts,jsx,tsx}";

/* Design tokens */
@import "@versaui/ui/react/styles/primitives.css";

/* Import only the themes you need (see Theming guide for all options) */
@import "@versaui/ui/react/styles/themes/core.css";
@import "@versaui/ui/react/styles/themes/glassmorphism.css";
/* @import "@versaui/ui/react/styles/themes/brutalism.css"; */
/* @import "@versaui/ui/react/styles/themes/humanist.css"; */

The @source directive tells Tailwind 4 to include Versa UI component files in its class detection. Adjust the path based on your project structure.

Base Styles

Add base styles for proper typography and colors:

@layer base {
  :root {
    font-family: var(--typography-font-family-body);
    line-height: var(--typescale-b3-line-height);
    font-weight: var(--typography-font-weight-body);
    color-scheme: light dark;
    color: var(--color-neutral-text-strong);
    background-color: var(--color-neutral-background-default);
    font-synthesis: none;
    text-rendering: optimizeLegibility;
    -webkit-font-smoothing: antialiased;
    -moz-osx-font-smoothing: grayscale;
  }

  h1, h2, h3, h4, h5, h6 {
    font-family: var(--typography-font-family-display);
  }

  body {
    margin: 0;
    min-width: 320px;
    min-height: 100vh;
    background-color: var(--color-neutral-background-default);
    color: var(--color-neutral-text-strong);
    font-family: var(--typography-font-family-body);
  }

  button {
    font-family: inherit;
    cursor: pointer;
  }
}

Theme & Mode Setup

Versa UI supports multiple themes and colour modes (light/dark). Set the active theme using data attributes on your root element:

<html data-theme="core" data-mode="light">

For detailed guidance on available themes, dynamic switching, customisation, and creating custom themes, see the Theming guide.

Provider Setup

Most Versa UI components are self-contained and don't require additional providers. Components like Modal, Dropdown, and Tooltip handle their own context internally.

Toast Provider

The Toast system requires a provider for stacking support:

import { ToastProvider, ToastViewport } from '@versaui/ui/react/ToastViewport';

function App() {
  return (
    <ToastProvider maxToasts={3}>
      <YourApp />
      <ToastViewport bottomOffset={24} />
    </ToastProvider>
  );
}

Icons

Versa UI uses Phosphor Icons throughout its components:

import { MagnifyingGlass, User, Bell } from '@phosphor-icons/react';

function MyComponent() {
  return (
    <div>
      <MagnifyingGlass size={20} weight="regular" />
      <User size={24} weight="duotone" />
      <Bell size={16} weight="fill" />
    </div>
  );
}

Available Weights: thin, light, regular (default), bold, fill, duotone

For theme-specific font families, see the Typography per Theme section in the Theming guide.

Accessibility

Versa UI components are built with accessibility as a core principle using React Aria for robust keyboard and screen reader support.

All interactive components support keyboard navigation:

Tab / Shift+Tab — Navigate between focusable elements
Enter / Space — Activate buttons and toggles
Arrow keys — Navigate within menus, accordions, and selects
Escape — Close modals, dropdowns, and tooltips

Focus Indicators

All focusable elements have visible focus rings using design tokens:

/* Focus ring tokens used internally */
--focus-ring-primary: 0 0 0 2px var(--color-brand-primary-subtler);
--focus-ring-neutral: 0 0 0 2px var(--color-neutral-surface-strong);

Semantic HTML elements used throughout
ARIA labels and descriptions where needed
Live regions for dynamic content updates (e.g., Toast notifications)
Focus management for modals and dialogs

Verify Your Setup

Let's verify your setup with a simple example:

import { Button } from '@versaui/ui/react/Button';
import { Tooltip } from '@versaui/ui/react/Tooltip';

function HelloVersaUI() {
  return (
    <div style={{ padding: '2rem' }}>
      <Tooltip content="Welcome to Versa UI!" placement="top">
        <Button variant="primary" size="default">
          Hover Me
        </Button>
      </Tooltip>
    </div>
  );
}

export default HelloVersaUI;

If you see a styled button with a tooltip on hover, your setup is complete!

Common Pitfalls

Missing CSS Imports

Symptom: Components render but have no styling or incorrect colors.

Fix: Ensure you've imported primitives.css and at least one theme file:

@import "@versaui/ui/react/styles/primitives.css";
@import "@versaui/ui/react/styles/themes/core.css";

Missing Theme Data Attributes

Symptom: Colors appear as undefined or fallback values.

Fix: Add theme and mode attributes to your root element:

<html data-theme="core" data-mode="light">

Tailwind Not Detecting Classes

Symptom: Some component styles are missing.

Fix: Add Versa UI to your Tailwind content configuration:

@source "../node_modules/@versaui/ui/react/dist/**/*.{js,ts,jsx,tsx}";

Font Loading Issues

Symptom: Fonts flash or fall back to system fonts.

Fix: Preload fonts in your HTML head:

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Manrope:wght@200..800&display=swap" rel="stylesheet">

React 18 Compatibility

Symptom: Hydration errors or ref warnings.

Fix: Some components use React 19 features. Ensure you're on React 18.3+ or upgrade to React 19:

npm install react@19 react-dom@19

Z-Index Conflicts

Symptom: Modals or dropdowns appear behind other elements.

Fix: Versa UI uses z-index values like 9999 for overlays. If you have conflicting z-index values, adjust your global styles or use the style prop on modal containers.

Next Steps

Now that you have Versa UI installed, explore:

Theming — Configure themes, customise tokens, and create your own themes
Button — Start with the most common component
Accordion — Learn about compound components
Modal — Build dialogs and overlays
Toast — Add notifications to your app