@appswave/ui-kit

A comprehensive, production-ready React component library built with modern web technologies

Overview

@appswave/ui-kit is a feature-rich React component library that provides a complete set of UI components, form controls, data tables, and utilities for building modern web applications. Built on top of Radix UI, shadcn/ui, and Tailwind CSS, it offers accessible, customizable, and performant components out of the box.

Features

• 🎨 Modern Design System - Built with Tailwind CSS and customizable theme support
• ♿ Accessible - All components follow WAI-ARIA guidelines via Radix UI primitives
• 📱 Responsive - Mobile-first design that works across all devices
• 🔧 TypeScript - Full TypeScript support with comprehensive type definitions
• 🎯 Form Integration - Seamless integration with React Hook Form and Zod validation
• 🎭 Theme Support - Built-in dark mode and theme customization
• 📊 Data Tables - Powerful, feature-rich data table components with sorting, filtering, and pagination
• 🚀 Tree-shakeable - Import only what you need for optimal bundle size
• 🎪 Composable - Flexible component composition for maximum customization

Installation

npm install @appswave/ui-kit
# or
yarn add @appswave/ui-kit
# or
pnpm add @appswave/ui-kit

Peer Dependencies

This library requires the following peer dependencies to be installed in your project:

npm install react@^19.0.0 react-dom@^19.0.0 react-hook-form@^7.53.0 zod@^3.23.8 @appswave/react-sdk@^1.0.0

Required Peer Dependencies

• react ^19.0.0
• react-dom ^19.0.0
• react-hook-form ^7.53.0
• zod ^3.23.8
• @appswave/react-sdk ^1.0.0

Quick Start

1. Setup CSS

This library uses Tailwind CSS v4, which requires the @source directive to scan library files for utility classes. Create or update your main CSS file (e.g., src/index.css) with:

@source "../node_modules/@appswave/ui-kit/dist/**/*.{js,jsx,ts,tsx}";
@import '../node_modules/@appswave/ui-kit/dist/styles.css';

Note: If you encounter export errors with the package alias (@appswave/ui-kit/styles.css), use the relative path import shown above, which is more reliable with Tailwind CSS v4's Vite plugin.

Then import this CSS file in your application's entry point (e.g., main.tsx or App.tsx):

import './index.css';

Why @source is needed: Tailwind CSS v4 scans your source files to generate utility classes. The @source directive tells Tailwind to also scan the library's bundled files in node_modules to generate the classes used by the library components.

2. Import Components

import { Button, Input, FormInput, DataTable } from '@appswave/ui-kit';

3. Use Components

import { Button } from '@appswave/ui-kit';

function App() {
  return (
    <div>
      <Button variant="default" size="default">
        Click me
      </Button>
    </div>
  );
}

Styling & Customization

CSS Setup

The library uses Tailwind CSS v4 with CSS custom properties (CSS variables) for theming. The @source directive is required to tell Tailwind to scan the library's bundled files for utility classes.

Overriding Theme Variables

You can override any theme variable by redefining CSS custom properties in your own CSS file. Important: Your overrides must come AFTER the import statement, and you can either use @layer base or define them directly. Here are both approaches:

Method 1: Using @layer base (Required)

The library's CSS variables are defined in @layer base, so your overrides MUST also be in @layer base to properly override them. This is the correct approach:

@source "../node_modules/@appswave/ui-kit/dist/**/*.{js,jsx,ts,tsx}";
@import '../node_modules/@appswave/ui-kit/dist/styles.css';

/* Override theme variables - MUST be in @layer base to override library's variables */
@layer base {
  :root {
    --primary: oklch(0.5 0.2 250); /* Custom primary color */
    --radius: 0.75rem; /* Custom border radius */
  }

  .dark {
    --primary: oklch(0.7 0.2 250); /* Custom primary for dark mode */
  }
}

Why @layer base is required: Tailwind CSS v4 processes CSS layers (@layer base, @layer components, @layer utilities) after regular CSS. Since the library defines variables in @layer base, your overrides must also be in @layer base to be in the same layer. Within the same layer, the last definition wins, so your variables (which come after the import) will override the library's.

Troubleshooting: If your overrides aren't working:

1. Ensure your CSS file is imported in your entry point (e.g., main.tsx)
2. Make sure the overrides come AFTER the @import statement
3. Clear your browser cache and restart your dev server
4. Check browser DevTools to verify the CSS variables are being applied

Available CSS Variables:

• Core Colors: --background, --foreground, --card, --card-foreground, --popover, --popover-foreground
• Semantic Colors: --primary, --primary-foreground, --secondary, --secondary-foreground, --accent, --accent-foreground, --destructive, --destructive-foreground, --muted, --muted-foreground, --success, --success-foreground, --warning, --warning-foreground, --info, --info-foreground
• Borders & Inputs: --border, --input, --ring
• Sidebar: --sidebar-background, --sidebar-foreground, --sidebar-primary, --sidebar-accent, --sidebar-border, --sidebar-ring
• Other: --radius, --font-sans, --font-mono, --font-serif

Overriding Component Styles

Using className Prop

Most components accept a className prop that you can use to override or extend styles:

import { Button } from '@appswave/ui-kit';

function App() {
  return (
    <Button 
      variant="default" 
      className="bg-blue-500 hover:bg-blue-600 text-white px-8"
    >
      Custom Styled Button
    </Button>
  );
}

Using Tailwind Utilities

You can use Tailwind's @layer directive to add custom utilities that override component styles:

@layer utilities {
  .custom-button {
    @apply bg-gradient-to-r from-purple-500 to-pink-500 text-white;
  }
}

Then use it:

<Button className="custom-button">Gradient Button</Button>

Using Theme Customizer

For visual theme customization at runtime, you can use the ThemeCustomizer component:

import { ThemeCustomizer } from '@appswave/ui-kit';

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

The ThemeCustomizer provides a UI to:

• Adjust colors for light and dark modes
• Change border radius
• Apply preset themes
• Copy generated CSS for permanent overrides

Complete Example

Here's a complete example showing CSS setup with custom overrides:

src/index.css:

@source "../node_modules/@appswave/ui-kit/dist/**/*.{js,jsx,ts,tsx}";
@import '../node_modules/@appswave/ui-kit/dist/styles.css';

@layer base {
  :root {
    /* Customize primary color */
    --primary: oklch(0.45 0.15 280);
    --primary-foreground: oklch(1 0 0);
    
    /* Customize border radius */
    --radius: 0.5rem;
    
    /* Customize fonts */
    --font-sans: 'Inter', system-ui, sans-serif;
  }
}

src/main.tsx:

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';
import './index.css'; // Import CSS here

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

Component Library

UI Components

Core UI components for building interfaces:

• Accordion - Collapsible content sections
• Alert - Display important messages and notifications
• App Charts - Chart components for data visualization
• Avatar - User profile images with fallback support
• Badge - Status indicators and labels
• Button - Interactive button component with multiple variants
• Calendar - Date picker calendar component
• Card - Container component for content grouping
• Checkbox - Checkbox input control
• Collapsible - Show/hide content sections
• Command - Command palette and search interface
• Dialog - Modal dialog component
• Divider - Visual separator component
• Dropdown Menu - Contextual menu component
• Formatted Number - Number formatting component
• Input - Text input field
• Label - Form label component
• Loading Button - Button with loading state
• Phone Input - International phone number input
• Popover - Floating content container
• Progress - Progress indicator component
• Rich Text Input - Rich text editor component
• Scroll Area - Custom scrollable container
• Scroll Selector - Scrollable selection component
• Select - Dropdown select component
• Sheet - Slide-out panel component
• Skeleton - Loading placeholder component
• Slider - Range slider input
• Switch - Toggle switch component
• Table - Table component for data display
• Tabs - Tabbed interface component
• Time Picker - Time selection component
• Toast - Toast notification component
• Toggle Group - Group of toggle buttons
• Tooltip - Hover tooltip component
• Tooltip Button - Button with integrated tooltip
• Upload File - File upload component
• Upload File Preview - File preview component
• File Upload Multi - Multi-file upload component

Form Components

React Hook Form integrated form components with validation support:

• FormContainer - Form wrapper component
• FormControl - Form control wrapper
• FormLabel - Form label component
• FormMessage - Form error/success message display
• FormInput - Text input with form integration
• FormSelect - Select dropdown with form integration
• FormCheckbox - Checkbox with form integration
• FormTextarea - Textarea with form integration
• FormUploadFile - File upload with form integration
• FormCombobox - Combobox with form integration
• FormMultiCombobox - Multi-select combobox with form integration
• FormDatePicker - Date picker with form integration
• FormDateRange - Date range picker with form integration
• FormNumber - Number input with form integration

Table Components

Advanced data table components with built-in features:

• DataTable - Main data table component
• DataTablePagination - Pagination controls for data tables
• DataTableToolbar - Toolbar with search and filters
• DataTableViewOptions - Column visibility and view options
• DataTableFacetedFilter - Faceted filtering component
• DataTableColumnHeader - Sortable column headers
• DataTableDateFilter - Date range filtering
• DataTableSkeleton - Loading skeleton for tables
• DataTableSliderFilter - Range slider filter

Shared Components

Utility and shared components:

• ActionPanel - Action panel component
• Breadcrumb - Navigation breadcrumb component
• Conditional - Conditional rendering component
• ConfirmDialog - Confirmation dialog component
• DateNavigation - Date navigation controls
• ErrorTooltip - Error tooltip component
• FacetedFilter - Faceted filtering component
• FormSubmitButton - Form submission button
• FormSubmitButtons - Multiple form action buttons
• LinkButton - Button styled as a link
• Loader - Loading spinner component
• MetaCard - Metadata card component
• PrimeCard - Primary card component
• PrimeDialog - Primary dialog component
• PrimeSheet - Primary sheet component
• Stepper - Step indicator component
• ThemeCustomizer - Theme customization interface
• ThemeSwitcher - Dark/light mode switcher
• Toaster - Toast notification provider
• TwoColumnMultiSelect - Two-column multi-select component

Usage Examples

Form with Validation

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import {
  FormContainer,
  FormInput,
  FormSelect,
  FormSubmitButton,
} from '@appswave/ui-kit';

const formSchema = z.object({
  name: z.string().min(2, 'Name must be at least 2 characters'),
  email: z.string().email('Invalid email address'),
  role: z.string().min(1, 'Please select a role'),
});

function MyForm() {
  const form = useForm({
    resolver: zodResolver(formSchema),
    defaultValues: {
      name: '',
      email: '',
      role: '',
    },
  });

  const onSubmit = (data) => {
    console.log(data);
  };

  return (
    <FormContainer form={form} onSubmit={form.handleSubmit(onSubmit)}>
      <FormInput
        control={form.control}
        name="name"
        label="Name"
        placeholder="Enter your name"
      />
      <FormInput
        control={form.control}
        name="email"
        label="Email"
        type="email"
        placeholder="Enter your email"
      />
      <FormSelect
        control={form.control}
        name="role"
        label="Role"
        options={[
          { value: 'admin', label: 'Admin' },
          { value: 'user', label: 'User' },
        ]}
      />
      <FormSubmitButton>Submit</FormSubmitButton>
    </FormContainer>
  );
}

Theme Customization

import { ThemeSwitcher, ThemeCustomizer } from '@appswave/ui-kit';

function App() {
  return (
    <div>
      <ThemeSwitcher />
      <ThemeCustomizer />
    </div>
  );
}

Development

Prerequisites

• Node.js 18+
• npm, yarn, or pnpm

Setup

# Clone the repository
git clone <repository-url>

# Install dependencies
yarn install

# Build the library
yarn build

# Watch mode for development
yarn dev

# Type checking
yarn type-check

# Linting
yarn lint

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

ISC

Made with ❤️ by AppsWave