Skip to main content

Getting Started with @xond/ui

@xond/ui is a comprehensive React component library built on Tailwind CSS, React Hook Form, and designed to work seamlessly with @xond/api generated services.

Installation​

Install @xond/ui in your React application:

pnpm add @xond/ui

Or if working within the Nufaza monorepo:

pnpm --filter @xond/ui install

Peer Dependencies​

@xond/ui requires several peer dependencies. Install them in your application:

pnpm add @headlessui/react @heroicons/react axios axios-hooks date-fns i18next lodash react react-dom react-hook-form react-router-dom

Import Styles​

Import the Tailwind CSS styles in your application entry point:

// src/main.tsx or src/index.tsx
import "@xond/ui/styles.css";
import "@xond/ui"; // This also imports the CSS

Tailwind Configuration​

@xond/ui uses Tailwind CSS. Ensure your tailwind.config.js includes the library's Tailwind entry:

// tailwind.config.js
module.exports = {
  content: [
    "./src/**/*.{js,jsx,ts,tsx}",
    "./node_modules/@xond/ui/dist/**/*.{js,jsx,ts,tsx}", // Include xond-ui components
  ],
  theme: {
    extend: {
      // Your custom theme extensions
    },
  },
  plugins: [],
};

Setup Providers​

Many @xond/ui components require context providers. Wrap your application with the necessary providers:

Notification Provider​

For toast notifications:

import { NotificationProvider } from "@xond/ui";

function App() {
  return (
    <NotificationProvider>
      {/* Your app content */}
    </NotificationProvider>
  );
}

Auth Provider (Optional)​

If using authentication:

import { BaseAuthProvider } from "@xond/ui";

function App() {
  return (
    <BaseAuthProvider>
      {/* Your app content */}
    </BaseAuthProvider>
  );
}

Basic Usage​

Import Components​

import { Button, TextInput, Table } from "@xond/ui";

Use Components​

function MyComponent() {
  return (
    <div>
      <Button onClick={() => alert("Clicked!")}>Click Me</Button>
      <TextInput label="Name" name="name" />
    </div>
  );
}

Component Categories​

@xond/ui components are organized into logical categories:

  • Base – Fundamental building blocks (Button, Alert, Link, Image)
  • Elements – UI primitives (Badge, Breadcrumb, Logo, Icons)
  • Inputs – Form controls (TextInput, Select, DateInput, etc.)
  • Layouts – Structural components (Modal, PageContainer, Tab)
  • Navigation – Navigation components (BottomNavigation, SideNavigation)
  • Table – Data display and manipulation (Table, Form, View, Paging)
  • View – Display components (ValueView, EntityCard, EncodedImageView)
  • Dashboard – Dashboard widgets (StatCards, FrequentModules)
  • UI – Specialized UI components (BalanceCard)

Integration with @xond/api​

@xond/ui is designed to work seamlessly with models generated by @xond/api:

import { modelRegistry, columnModelRegistry } from "@your-app/generated/models";
import { Table } from "@xond/ui";

function UsersTable() {
  const UserModel = modelRegistry.user;
  const UserColumns = columnModelRegistry.user;

  return (
    <Table
      model={UserModel}
      columns={UserColumns}
      // ... other props
    />
  );
}

Next Steps​