Alpha UI - React Component Library

A modern, polished React component library built with TypeScript, Tailwind CSS, and CSS-in-JS. Alpha UI provides a comprehensive set of accessible, customizable components for building beautiful user interfaces.

Features

✨ 20+ Production-Ready Components

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

🎨 Beautiful Styling

• Built with Tailwind CSS
• Dark mode support out of the box
• Fully customizable through design tokens
• Smooth transitions and animations

♿ Accessibility First

• Semantic HTML
• ARIA attributes
• Keyboard navigation support
• Screen reader optimized

📚 Complete Documentation

• Storybook integration for interactive component exploration
• TypeScript definitions
• Comprehensive prop documentation
• Usage examples for each component

🚀 Developer Experience

• Zero-config setup
• ESM and CommonJS support
• Tree-shakeable exports
• Small bundle size (~15KB gzipped)

Installation

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

Quick Start

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

export default function App() {
  return (
    <div>
      <Card>
        <h1>Welcome to Alpha UI</h1>
        <Input placeholder="Enter your name" />
        <Button variant="primary">Submit</Button>
      </Card>
    </div>
  )
}

Documentation and Examples

• Full docs site: app/docs/page.tsx
• Interactive examples (Storybook):

npm run storybook

• Static Storybook build:

npm run build-storybook

Components

Basic Components

Button

import { Button } from 'alpha-ui'

// 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'

<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'

<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'

// 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'

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

Avatar

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

<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'

// 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'

// 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'

<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'

<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'
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'

<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'

<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'

<Tooltip content="Help text" position="top">
  <Button>Hover me</Button>
</Tooltip>

Toast

import { Toast, useToast } from 'alpha-ui'

function MyComponent() {
  const { addToast } = useToast()
  
  return (
    <Button onClick={() => addToast('Success!', 'success')}>
      Show Toast
    </Button>
  )
}

Data Display Components

Table

import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from 'alpha-ui'

<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'

<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'

<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'

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