Installation

Install ReactUI Library in your project using your preferred package manager, then follow the framework-specific guide for your setup.

Package Managers

ReactUI is distributed as a single package on npm. Choose the command that matches your package manager.

npmnpm

npm install @reactui/core

If you prefer to install an exact version, append the version tag:

npm install @reactui/core@2.4.0

yarnYarn

yarn add @reactui/core

For Yarn Berry (v2+), make sure PnP is configured or use nodeLinker: node-modules in your .yarnrc.yml.

pnpmpnpm

pnpm add @reactui/core

pnpm uses a content-addressable store, making installs faster and saving disk space. No extra configuration is required.

Peer Dependencies

ReactUI requires React 18 or later. Most projects already have these installed. If not, add them alongside the core package.

"peerDependencies": {
  "react": ">=18.0.0",
  "react-dom": ">=18.0.0"
}

Install them explicitly if they are missing:

npm install react react-dom

Optional Dependencies

Some features require additional packages. These are listed per component in the API reference but are not required for the core library to function.

# Date picker -- requires date-fns
npm install date-fns

# Rich text editor -- requires tiptap
npm install @tiptap/react @tiptap/starter-kit

# Charts -- requires recharts
npm install recharts

Framework-Specific Setup

ReactUI works with any React framework. Below are step-by-step configuration guides for the three most popular setups.

Next.js (App Router)

ReactUI is fully compatible with the Next.js App Router and server components. Most ReactUI components work as server components out of the box; interactive ones (modals, dropdowns) include the "use client" directive automatically.

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  // ReactUI works out of the box.
  // Enable transpilePackages if you see ESM issues:
  transpilePackages: ['@reactui/core'],
};

module.exports = nextConfig;

// app/layout.tsx
import { ReactUIProvider } from '@reactui/core';
import '@reactui/core/styles.css';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <ReactUIProvider theme="system">
          {children}
        </ReactUIProvider>
      </body>
    </html>
  );
}

Vite

Vite works seamlessly with ReactUI thanks to its native ESM support. No extra plugins are needed for basic usage.

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  // Optional: alias for cleaner imports
  resolve: {
    alias: {
      '@': '/src',
    },
  },
});

// src/main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { ReactUIProvider } from '@reactui/core';
import '@reactui/core/styles.css';
import App from './App';

ReactDOM.createRoot(
  document.getElementById('root')!
).render(
  <React.StrictMode>
    <ReactUIProvider theme="light">
      <App />
    </ReactUIProvider>
  </React.StrictMode>
);

Create React App

CRA requires no additional configuration. Install the package and wrap your app with the provider.

// src/index.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { ReactUIProvider } from '@reactui/core';
import '@reactui/core/styles.css';
import App from './App';

const root = ReactDOM.createRoot(
  document.getElementById('root') as HTMLElement
);

root.render(
  <React.StrictMode>
    <ReactUIProvider theme="light">
      <App />
    </ReactUIProvider>
  </React.StrictMode>
);

Note: If you are using CRA v5 with Webpack 5, CSS imports work automatically. For older versions you may need to eject or use craco to customize the Webpack config.

Verify Your Installation

Create a simple test component to confirm everything is wired up correctly. If the button renders with proper styling and responds to clicks, your setup is complete.

// app/page.tsx  or  src/App.tsx
import { Button, Card, Stack, Text } from '@reactui/core';

export default function TestPage() {
  return (
    <div style={{ padding: '2rem' }}>
      <Card padding="lg" variant="elevated">
        <Stack spacing="md">
          <Text variant="h3">
            ReactUI is Working!
          </Text>
          <Text variant="body" color="muted">
            If you can see this styled card with a button
            below, your installation is successful.
          </Text>
          <Button
            variant="primary"
            onClick={() => alert('ReactUI is installed correctly!')}
          >
            Click Me
          </Button>
        </Stack>
      </Card>
    </div>
  );
}

Run your dev server (npm run dev) and open the page in your browser. You should see a styled card with a heading, paragraph text, and a primary-colored button.

Troubleshooting

Components render without styles

Make sure you have imported @reactui/core/styles.css in your root layout or entry file. This stylesheet must be loaded before any components render.

Module not found errors

Delete your node_modules folder and lock file, then reinstall. For Next.js, add @reactui/core to the transpilePackages array in next.config.js.

TypeScript type errors

Ensure your tsconfig.json includes "moduleResolution": "bundler" or "node16". ReactUI ships with full type definitions, but older module resolution strategies may fail to locate them.

← Getting Started Theming →