⚡ Alpha UI

Next-Generation React Component Library

Enterprise-Grade • Production-Ready • Developer-Friendly

🎯 Live Demo • 📖 Documentation • 🎨 Storybook • 💬 Support

🌟 Why Alpha UI?

Build stunning, accessible UIs 50% faster with production-ready components that work out of the box.

| Feature | Alpha UI | Others | |---------|--------|--------| | Components | 40+ | ~20-30 | | TypeScript | ✅ Native Support | ⚠️ Partial | | Accessibility | ✅ WCAG 2.1 AA | ⚠️ Limited | | Dark Mode | ✅ Built-in | ⚠️ Extra work | | Bundle Size | ~15KB gzipped | ~25-50KB | | Setup Time | < 2 minutes | ~10 minutes |

✨ Key Features

🎯 40+ Components

• Form: Button, Input, Select, Checkbox, Radio, Switch, TextField
• Display: Card, Badge, Avatar, Alert, Progress, Stepper
• Layout: Container, Grid, Navbar, Sidebar, Accordion
• Interactive: Modal, Tooltip, Dropdown, Tabs, Toast
• Data: Table, Pagination, Calendar, TransferList

🎨 Beautiful & Consistent

• Dark mode support ☀️🌙
• Smooth animations
• Design tokens & theming
• Responsive by default
• Custom color palette

♿ Accessibility Built-In

• WCAG 2.1 Level AA
• Semantic HTML
• ARIA attributes
• Keyboard navigation
• Focus management

🚀 Developer Experience

• TypeScript first
• Tree-shakeable
• Zero-config
• ESM & CJS
• Small bundle
• Hot reload ready

📦 Installation

npm install alpha-ui-kit
# or
yarn add alpha-ui-kit
# or
pnpm add alpha-ui-kit

🚀 Quick Start

1️⃣ Import and Use

import { Button, Card, Input } from 'alpha-ui-kit'
import 'alpha-ui-kit/styles.css'

export default function App() {
  return (
    <Card className="p-8 max-w-md mx-auto mt-10">
      <h1 className="text-2xl font-bold mb-4">Welcome to Alpha UI</h1>
      <Input 
        type="email"
        placeholder="Enter your email"
        className="mb-4"
      />
      <Button 
        variant="contained" 
        color="primary" 
        fullWidth
      >
        Get Started
      </Button>
    </Card>
  )
}

2️⃣ Customize Your Theme

import { ThemeProvider } from 'alpha-ui-kit'

export default function App() {
  return (
    <ThemeProvider mode="dark" customColors={{
      primary: '#3b82f6',
      secondary: '#8b5cf6',
    }}>
      {/* Your app here */}
    </ThemeProvider>
  )
}

🎯 Live Demo

• Interactive Components: Storybook Live
• Full Documentation: docs.novaUI.dev
• Component Showcase: components.novaUI.dev

📖 Documentation

Getting Started

• Installation Guide
• Setup & Configuration
• Theme Customization
• Dark Mode

Components

• Button
• Input & Form Elements
• Card & Layout
• Modal & Dialogs
• Data Display
• See All Components →

Advanced

• Accessibility (A11y)
• TypeScript Support
• Performance Tips
• Troubleshooting

🎨 Interactive Exploration

Explore all components interactive with Storybook:

npm run storybook

Build Storybook for production:

npm run build-storybook

💡 Component Examples

Button Component

import { Button } from 'alpha-ui-kit'

// Variants: contained, outlined, text (plus legacy variants)
// Colors: primary, secondary, success, error, warning, info, inherit
// Sizes: small|medium|large (also sm|md|lg)
<Button variant="contained" color="primary" size="medium">
  Click me
</Button>

// Loading state
<Button isLoading loadingPosition="start">Loading...</Button>

// Icons and full width
<Button startIcon={<Plus />} endIcon={<ArrowRight />} fullWidth>
  Continue
</Button>

// Disabled state
<Button disabled>Disabled</Button>

Input

import { Input } from 'alpha-ui-kit'

<Input
  label="Email"
  type="email"
  placeholder="[email protected]"
  variant="default"
  size="md"
  error="Invalid email"
  helperText="Enter a valid email address"
/>

Card

import { Card, CardHeader, CardTitle, CardContent, CardFooter } from 'alpha-ui-kit'

<Card variant="elevated">
  <CardHeader>
    <CardTitle>Card Title</CardTitle>
  </CardHeader>
  <CardContent>
    <p>Card content goes here</p>
  </CardContent>
  <CardFooter>
    {/* Footer content */}
  </CardFooter>
</Card>

Badge

import { Badge } from 'alpha-ui-kit'

// Variants: default, primary, success, warning, danger
// Sizes: sm, md, lg
<Badge variant="primary" size="md">
  New
</Badge>

Alert

import { Alert, AlertTitle, AlertDescription } from 'alpha-ui-kit'

<Alert variant="success" closable>
  <AlertTitle>Success!</AlertTitle>
  <AlertDescription>Your changes have been saved.</AlertDescription>
</Alert>

Avatar

import { Avatar, AvatarImage, AvatarFallback } from 'alpha-ui-kit'

<Avatar size="md" shape="circle">
  <AvatarImage src="https://avatar.com/user.jpg" alt="User" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

Layout Components

Container

import { Container } from 'alpha-ui-kit'

// Sizes: sm, md, lg, xl, full
// Padding: sm, md, lg
<Container size="xl" py="lg">
  <h1>Centered content</h1>
</Container>

Grid

import { Grid } from 'alpha-ui-kit'

// Columns: 1-12, Responsive: true/false
<Grid columns={3} gap="md" responsive>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Grid>

Navbar

import { Navbar, NavbarBrand, NavbarNav, NavbarItem } from 'alpha-ui-kit'

<Navbar>
  <NavbarBrand>
    <h1>MyApp</h1>
    <NavbarNav>
      <NavbarItem href="/">Home</NavbarItem>
      <NavbarItem href="/about">About</NavbarItem>
      <NavbarItem href="/contact">Contact</NavbarItem>
    </NavbarNav>
  </NavbarBrand>
</Navbar>

Sidebar

import { Sidebar, SidebarContent, SidebarItem } from 'alpha-ui-kit'

<Sidebar>
  <SidebarContent>
    <SidebarItem href="/" active>
      Dashboard
    </SidebarItem>
    <SidebarItem href="/settings">
      Settings
    </SidebarItem>
  </SidebarContent>
</Sidebar>

Interactive Components

Modal

import { Modal, ModalHeader, ModalTitle, ModalBody, ModalFooter } from 'alpha-ui-kit'
import { useState } from 'react'

function MyModal() {
  const [isOpen, setIsOpen] = useState(false)
  
  return (
    <>
      <Button onClick={() => setIsOpen(true)}>Open Modal</Button>
      <Modal isOpen={isOpen} onClose={() => setIsOpen(false)} size="md">
        <ModalHeader>
          <ModalTitle>Modal Title</ModalTitle>
        </ModalHeader>
        <ModalBody>Modal content</ModalBody>
        <ModalFooter>
          <Button onClick={() => setIsOpen(false)}>Close</Button>
        </ModalFooter>
      </Modal>
    </>
  )
}

Tabs

import { Tabs, TabsList, TabsTrigger, TabsContent } from 'alpha-ui-kit'

<Tabs defaultValue="tab1">
  <TabsList>
    <TabsTrigger value="tab1">Tab 1</TabsTrigger>
    <TabsTrigger value="tab2">Tab 2</TabsTrigger>
  </TabsList>
  <TabsContent value="tab1">Content 1</TabsContent>
  <TabsContent value="tab2">Content 2</TabsContent>
</Tabs>

Accordion

import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from 'alpha-ui-kit'

<Accordion>
  <AccordionItem value="item1">
    <AccordionTrigger>Item 1</AccordionTrigger>
    <AccordionContent>Content 1</AccordionContent>
  </AccordionItem>
  <AccordionItem value="item2">
    <AccordionTrigger>Item 2</AccordionTrigger>
    <AccordionContent>Content 2</AccordionContent>
  </AccordionItem>
</Accordion>

Tooltip

import { Tooltip } from 'alpha-ui-kit'

### Button Component

```tsx
import { Button } from 'alpha-ui-kit'

// All variants with sizes and colors
<Button variant="contained" color="primary">Primary</Button>
<Button variant="outlined" color="secondary">Secondary</Button>
<Button variant="text" color="success">Success</Button>

// With icons and states
<Button startIcon={<Plus />} isLoading>Loading...</Button>
<Button disabled fullWidth>Disabled</Button>

Form Components

import { Input, Select, Checkbox, Switch } from 'alpha-ui-kit'

// Flexible input with validation
<Input 
  label="Email"
  type="email"
  error="Invalid format"
  helperText="Enter a valid email"
/>

// Rich select
<Select options={items} placeholder="Choose..." searchable />

// Toggle components
<Checkbox label="Accept terms" />
<Switch label="Dark mode" onChange={handleToggle} />

Data Display

import { Table, Pagination, Card, Badge } from 'alpha-ui-kit'

// Beautiful table with pagination
<Table data={rows} columns={columns} sortable filterable>
  <Table.Head />
  <Table.Body />
</Table>

// Pagination controls
<Pagination total={100} pageSize={10} onPageChange={setPage} />

// Status badges
<Badge variant="success">Active</Badge>
<Badge variant="warning">Pending</Badge>
<Badge variant="danger">Critical</Badge>

Layout & Navigation

import { Container, Grid, Card, Navbar } from 'alpha-ui-kit'

// Responsive grid
<Grid columns={{ sm: 1, md: 2, lg: 3 }} gap="lg">
  <Card>Card 1</Card>
  <Card>Card 2</Card>
  <Card>Card 3</Card>
</Grid>

// Full responsive layout
<Navbar branding="MyApp">
  <Navbar.Menu>
    <Navbar.Item href="/">Home</Navbar.Item>
    <Navbar.Item href="/docs">Docs</Navbar.Item>
  </Navbar.Menu>
</Navbar>

📊 Component Status

| Category | Count | Status | |----------|-------|--------| | Form Elements | 12 | ✅ Complete | | Layout | 8 | ✅ Complete | | Data Display | 10 | ✅ Complete | | Feedback | 6 | ✅ Complete | | Navigation | 4 | ✅ Complete | | Advanced | 2+ | 🚀 In Progress |

🎓 Learning Resources

• 📚 Complete API Reference - All props and methods
• 🎥 Video Tutorials - Step-by-step guides
• 🔧 Customization Guide - Theming & styling
• 💻 CodeSandbox Examples - Interactive demos
• 🎯 Best Practices - Pro tips & patterns

🤝 Contributing

We love contributions! Here's how to get started:

# 1. Fork & clone the repository
git clone https://github.com/yourusername/nova-ui.git

# 2. Install dependencies
npm install

# 3. Create a feature branch
git checkout -b feature/my-feature

# 4. Make your changes and add tests
npm run test

# 5. Run linting
npm run lint

# 6. Push and create a Pull Request
git push origin feature/my-feature

Contributing Guidelines:

• ✅ Write tests for new features
• ✅ Follow our Code of Conduct
• ✅ Update documentation
• ✅ Keep commits clean and descriptive

See CONTRIBUTING.md for detailed guidelines.

🐛 Bug Reports & Feature Requests

• Found a bug? Open an Issue
• Have a feature idea? Start a Discussion
• Security concern? Report privately

💬 Community & Support

• Discord Community: Join us - Get help, share ideas, and connect with other developers
• GitHub Discussions: Ask questions - Engage with maintainers and community
• Twitter: @NovaUI - Latest updates and announcements
• Email Support: [email protected]

📈 Performance Metrics

• Bundle Size: ~15KB gzipped (components only)
• Tree-Shakeable: ✅ Import only what you need
• Performance Score: 98/100 Lighthouse
• Accessibility: WCAG 2.1 Level AA
• Type Safety: 100% TypeScript

🗺️ Roadmap

Q2 2026

• [ ] Advanced Form Components (DatePicker, TimePicker)
• [ ] Chart Components
• [ ] Virtual Scrolling for Large Lists
• [ ] Animation Presets

Q3 2026

• [ ] Mobile-specific Components
• [ ] Internationalization (i18n)
• [ ] Component Builder Tool
• [ ] Design Tokens Studio

See full roadmap →

📄 License

MIT © 2024-2026 NovaUI Contributors

This project is open source and available under the MIT License.

🌟 Show Your Support

If NovaUI helps you build amazing things, please consider:

• ⭐ Star us on GitHub - It helps other developers discover NovaUI
• 🐦 Share on Twitter - Spread the word about your awesome project
• 💬 Leave Feedback - Help us improve by sharing your thoughts
• 🤝 Contribute - Join our community of contributors

Built with ❤️ by the NovaUI Team

Get Started • View Components • Join Community

return ( <Button onClick={() => addToast('Success!', 'success')}> Show Toast ) }

### Data Display Components

#### Table
```tsx
import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from 'alpha-ui-kit'

<Table>
  <TableHeader>
    <TableRow>
      <TableHead>Name</TableHead>
      <TableHead>Email</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>John Doe</TableCell>
      <TableCell>[email protected]</TableCell>
    </TableRow>
  </TableBody>
</Table>

Pagination

import { Pagination, PaginationContent, PaginationItem, PaginationLink, PaginationPrevious, PaginationNext } from 'alpha-ui-kit'

<Pagination>
  <PaginationContent>
    <PaginationItem>
      <PaginationPrevious href="#" />
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="#" isActive>1</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="#">2</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationNext href="#" />
    </PaginationItem>
  </PaginationContent>
</Pagination>

Publishing to npm

1. Verify package metadata in package.json:

• name
• version
• main/module/types
• exports

2. Run quality checks and build:

npm run lint
npm run build:lib
npm run build-storybook

3. Login to npm:

npm login

4. Dry-run package contents:

npm pack --dry-run

5. Publish:

npm publish --access public

6. For updates:

npm version patch   # or minor / major
npm publish --access public

Stepper

import { Stepper, StepperItem, StepperContent } from 'alpha-ui-kit'

<Stepper activeStep={1}>
  <StepperItem step={0}>
    <StepperContent>
      <h4>Step 1</h4>
      <p>First step content</p>
    </StepperContent>
  </StepperItem>
  <StepperItem step={1}>
    <StepperContent>
      <h4>Step 2</h4>
      <p>Second step content</p>
    </StepperContent>
  </StepperItem>
</Stepper>

Customization

All components support Tailwind CSS classes and can be customized through the className prop:

<Button className="w-full text-lg">
  Full Width Button
</Button>

<Card className="max-w-2xl">
  Custom width card
</Card>

Dark Mode

Alpha UI components include built-in dark mode support. Enable it by adding the dark class to your root element:

<div className="dark">
  <MyComponent />
</div>

Storybook Documentation

View interactive component documentation and examples:

npm run storybook

This opens Storybook at http://localhost:6006 where you can explore all components with interactive controls.

TypeScript Support

Alpha UI is built with TypeScript and provides full type definitions:

import { Button, type ButtonProps } from 'alpha-ui-kit'

const CustomButton: React.FC<ButtonProps> = (props) => {
  return <Button {...props} />
}

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

License

MIT

Contributing

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

Support

For issues, questions, or suggestions, please create an issue on GitHub.

Built with ❤️ by the Alpha UI team