npm package: @preline-react/ui
Description: React component library built on [Preline UI](https://preline.co) with Tailwind v4. Router-agnostic — works with react-router-dom and @tanstack/react-router.
Latest version: 0.1.5

# @preline-react/ui

React component library built on [Preline UI](https://preline.co) with Tailwind v4. Router-agnostic — works with react-router-dom and @tanstack/react-router.

## Installation

```bash
npm install @preline-react/ui
```

## Quick Setup

```bash
npx preline-ui init
```

This configures Tailwind, Preline, and installs the router of your choice.

## Router Setup

Wrap your app with the appropriate router provider:

### react-router-dom

```tsx
import { BrowserRouter, Routes, Route } from 'react-router-dom';
import { ReactRouterProvider } from '@preline-react/ui/react-router';
import { MainLayout } from '@preline-react/ui';

function App() {
  return (
    <BrowserRouter>
      <ReactRouterProvider>
        <Routes>
          <Route element={<MainLayout navItems={navItems} account={account} />}>
            <Route path="/" element={<HomePage />} />
          </Route>
        </Routes>
      </ReactRouterProvider>
    </BrowserRouter>
  );
}
```

### @tanstack/react-router

```tsx
import { RouterProvider, createRouter, createRootRoute, createRoute } from '@tanstack/react-router';
import { TanStackRouterProvider } from '@preline-react/ui/tanstack-router';
import { MainLayout } from '@preline-react/ui';

const rootRoute = createRootRoute({
  component: () => (
    <TanStackRouterProvider>
      <MainLayout navItems={navItems} account={account} />
    </TanStackRouterProvider>
  ),
});

const indexRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/',
  component: HomePage,
});

const router = createRouter({ routeTree: rootRoute.addChildren([indexRoute]) });

function App() {
  return <RouterProvider router={router} />;
}
```

## Scaffold

Generate a ready-to-use `App.tsx` and `HomePage.tsx`:

```bash
npx preline-ui b2b
```

Prompts for your router choice and generates files in `src/`.

## Components

### UI Primitives

```tsx
import { Button, Input, Badge, Avatar, Toggle, Tooltip } from '@preline-react/ui';
// Or direct imports for minimal bundle:
import { Button } from '@preline-react/ui/button';
```

- `Avatar` — User avatar with initials fallback
- `Badge` — Status badges
- `Button` — Button with variants
- `Checkbox` — Checkbox input
- `DataTable` — Data table with column config (`selectable` prop for row checkboxes)
- `Icon` — Lucide icon wrapper
- `Input` — Text input
- `InputNumber` — Number input
- `Select` — Select dropdown
- `SkeletonTable` — Table loading skeleton
- `Textarea` — Textarea input
- `Toggle` — Toggle switch
- `Tooltip` — Tooltip wrapper

### Layout

```tsx
import { MainLayout, Header, NavBar } from '@preline-react/ui';
```

- `MainLayout` — Full page layout with Header + Outlet + SearchModal
- `Header` — Top bar with brand, search, notifications, account
- `NavBar` — Navigation bar with links and dropdowns
- `SearchModal` — Command palette search modal

## Layout Configuration

```tsx
import type { NavItem, AccountConfig, HelpItem, NotificationsConfig } from '@preline-react/ui';

const navItems: NavItem[] = [
  { type: 'link', to: '/', label: 'Dashboard', icon: TrendingUp },
  {
    type: 'dropdown',
    id: 'settings-dd',
    label: 'Settings',
    icon: Settings,
    children: [
      { to: '/settings/general', label: 'General' },
      { to: '/settings/billing', label: 'Billing' },
    ],
  },
];

const account: AccountConfig = {
  initials: 'JD',
  menuItems: [
    { label: 'Settings', icon: Settings },
    { label: 'Sign out' },
  ],
};

<MainLayout
  brand={{ label: 'My App', to: '/' }}
  navItems={navItems}
  account={account}
  helpItems={helpItems}
  notifications={notifications}
  searchPlaceholder="Search..."
/>
```

## Theming

Set attributes on `<html>` to control the theme:

```html
<html data-theme="theme-moon" data-brand="gray" data-font="sans">
```

- `data-theme` — `theme` (light) or `theme-moon` (dark)
- `data-brand` — Brand color: `blue`, `gray`, `green`, `red`, `orange`, `violet`, etc.
- `data-font` — Font family: `sans`, `serif`, `mono`