npm package: 21st-kit
Description: A modern React UI component library
Author: Bharadwaj Apittu
Latest version: 0.1.4

# 21st-Kit

A modern React UI component library designed for building beautiful, accessible, and responsive web applications.

[![npm version](https://img.shields.io/npm/v/21st-kit.svg)](https://www.npmjs.com/package/21st-kit)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

## Features

- 🎨 **Modern Design**: Clean, minimal, and customizable components
- 🧩 **Composable**: Components designed to work together seamlessly
- 📱 **Responsive**: Mobile-first design approach
- ♿ **Accessible**: Built with accessibility in mind (WCAG 2.1 compliant)
- 🌗 **Themeable**: Easily customize colors, spacing, and more
- 🔍 **TypeScript**: Full TypeScript support with comprehensive type definitions
- 🧪 **Well-tested**: Thoroughly tested components
- 📦 **Tree-shakable**: Only import what you need
- 🔄 **Controlled & Uncontrolled**: Support for both controlled and uncontrolled components

## Installation

```bash
# npm
npm install 21st-kit

# yarn
yarn add 21st-kit

# pnpm
pnpm add 21st-kit
```

## Quick Start

```jsx
import React from 'react';
import { ThemeProvider, Button, Card, CardContent } from '21st-kit';
import '21st-kit/dist/index.css';

function App() {
  return (
    <ThemeProvider>
      <Card>
        <CardContent>
          <h2>Hello, 21st-Kit!</h2>
          <p>A modern React UI component library</p>
          <Button>Get Started</Button>
        </CardContent>
      </Card>
    </ThemeProvider>
  );
}

export default App;
```

## Components

### Basic Components

- **Button**: Various styles, sizes, and states
- **Card**: Flexible container with header, content, and footer
- **Avatar**: User avatars with image fallback
- **Badge**: Small status indicators
- **Alert**: Contextual feedback messages
- **Progress**: Progress indicators
- **Tooltip**: Informative text when hovering over elements

### Form Components

- **Input**: Text input fields
- **Textarea**: Multi-line text input
- **Select**: Dropdown selection
- **Checkbox**: Single checkbox
- **Radio**: Radio button groups
- **Switch**: Toggle switches
- **Form**: Complete form system with validation states

### Navigation Components

- **Tabs**: Tabbed interfaces with controlled and uncontrolled versions

## Theme Customization

21st-Kit comes with a powerful theming system that allows you to customize the look and feel of your application.

```jsx
import { ThemeProvider } from '21st-kit';

function App() {
  const customTheme = {
    colors: {
      primary: '#0070f3',
      secondary: '#7928ca',
      // Override other colors as needed
    },
    borderRadius: {
      md: '0.5rem',
      // Override other border radiuses as needed
    },
    // Override other theme values as needed
  };

  return (
    <ThemeProvider theme={customTheme}>
      {/* Your app content */}
    </ThemeProvider>
  );
}
```

## Form Integration

21st-Kit works seamlessly with popular form libraries like React Hook Form and Formik.

### React Hook Form Example

```jsx
import { useForm, Controller } from 'react-hook-form';
import { Form, FormItem, FormLabel, FormControl, FormMessage, Input, Button } from '21st-kit';

function LoginForm() {
  const { control, handleSubmit, formState: { errors } } = useForm({
    defaultValues: {
      email: '',
      password: '',
    }
  });

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

  return (
    <Form onSubmit={handleSubmit(onSubmit)}>
      <FormItem validationState={errors.email ? 'invalid' : 'default'}>
        <FormLabel required>Email</FormLabel>
        <FormControl>
          <Controller
            name="email"
            control={control}
            rules={{ 
              required: 'Email is required',
              pattern: { 
                value: /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i, 
                message: 'Invalid email address' 
              }
            }}
            render={({ field }) => (
              <Input 
                type="email" 
                placeholder="Enter your email" 
                {...field} 
              />
            )}
          />
        </FormControl>
        <FormMessage error={errors.email?.message} />
      </FormItem>
      
      {/* Password field and submit button */}
    </Form>
  );
}
```

## Controlled vs Uncontrolled Components

Many components in 21st-Kit support both controlled and uncontrolled usage patterns.

### Controlled Tabs Example

```jsx
import { useState } from 'react';
import { Tabs, TabsList, TabsTrigger, TabsContent } from '21st-kit';

function ControlledTabs() {
  const [activeTab, setActiveTab] = useState('tab1');
  
  return (
    <Tabs value={activeTab} onValueChange={setActiveTab}>
      <TabsList>
        <TabsTrigger value="tab1">Tab 1</TabsTrigger>
        <TabsTrigger value="tab2">Tab 2</TabsTrigger>
      </TabsList>
      <TabsContent value="tab1">Content for Tab 1</TabsContent>
      <TabsContent value="tab2">Content for Tab 2</TabsContent>
    </Tabs>
  );
}
```

### Uncontrolled Tabs Example

```jsx
import { Tabs, TabsList, TabsTrigger, TabsContent } from '21st-kit';

function UncontrolledTabs() {
  return (
    <Tabs defaultValue="tab1">
      <TabsList>
        <TabsTrigger value="tab1">Tab 1</TabsTrigger>
        <TabsTrigger value="tab2">Tab 2</TabsTrigger>
      </TabsList>
      <TabsContent value="tab1">Content for Tab 1</TabsContent>
      <TabsContent value="tab2">Content for Tab 2</TabsContent>
    </Tabs>
  );
}
```

## Button Variants

21st-Kit provides multiple button variants to suit different UI needs:

```jsx
import { Button } from '21st-kit';

function ButtonExamples() {
  return (
    <div>
      <Button variant="primary">Primary</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="outline">Outline</Button>
      <Button variant="text">Text</Button>
      <Button variant="ghost">Ghost</Button>
      <Button variant="link">Link</Button>
      <Button variant="danger">Danger</Button>
      <Button variant="success">Success</Button>
      <Button variant="warning">Warning</Button>
      <Button variant="info">Info</Button>
      
      {/* Icon buttons */}
      <Button size="icon" aria-label="Settings">
        <SettingsIcon />
      </Button>
      
      {/* Loading state */}
      <Button loading>Loading</Button>
      
      {/* With icons */}
      <Button leftIcon={<DownloadIcon />}>Download</Button>
      <Button rightIcon={<ArrowRightIcon />}>Next</Button>
    </div>
  );
}
```

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for more details.

## License

MIT © [Bharadwaj Apittu](https://github.com/yourusername)