README.md · adnaan/React UI组件库

# Adnaan UI

A modern, beautiful, and highly customizable React UI component library with stunning animations and theme support.

[![NPM Version](https://img.shields.io/npm/v/adnaan-ui?style=flat-square)](https://www.npmjs.com/package/adnaan-ui)
[![Bundle Size](https://img.shields.io/badge/bundle-48KB-success?style=flat-square)](https://www.npmjs.com/package/adnaan-ui)
[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg?style=flat-square)](https://www.typescriptlang.org/)

**📦 110KB Package | 48KB ESM | 13 Components | Full TypeScript Support**

**English** | [简体中文](./README.zh-CN.md)

</div>

## ✨ Features

- 🎨 **Beautiful Components** - Modern, carefully designed UI components
- 🌈 **Theme Support** - Built-in light/dark themes with CSS variables
- 🎭 **Smooth Animations** - Powered by Framer Motion
- 📦 **Tree Shaking** - Only import what you need
- 💪 **TypeScript** - Full type definitions included
- 🔧 **Customizable** - Easy to customize with CSS variables
- ⚡ **High Performance** - Optimized for production
- 🌐 **Global API** - Convenient global UI utilities (toast, modal, etc.)

## 📦 Installation

```bash
npm install adnaan-ui
```

### Peer Dependencies

Make sure you have these installed:

```bash
npm install react react-dom @emotion/react @emotion/styled framer-motion react-icons
```

## 🚀 Quick Start

### 1. Import Styles

Import the default theme styles in your app entry file:

```tsx
// main.tsx or App.tsx
import 'adnaan-ui/styles'; // 可选：仅包含必要的样式类（如 scroll-lock）
```

### 2. Use Components

```tsx
import { Button, Input, Modal } from 'adnaan-ui';

function App() {
  return (
    <div>
      <Button variant="primary">Click Me</Button>
      <Input placeholder="Enter text..." />
    </div>
  );
}
```

### 3. Use Global UI Tools

Initialize global UI at your app entry:

```tsx
// main.tsx
import { initAdnaanUI } from 'adnaan-ui';

initAdnaanUI();

// Now you can use anywhere in your app:
adnaan.toast.success('Operation successful!');
adnaan.modal.confirm({
  title: 'Confirm Action',
  message: 'Are you sure?',
}).then(confirmed => {
  if (confirmed) {
    // Do something
  }
});
```

## 📚 Components

### Basic Components

- **Button** - Multiple variants, sizes, and loading states
- **Input** - Text input with validation and icons
- **Textarea** - Multi-line text input
- **Badge** - Status indicators
- **Tabs** - Tab navigation
- **Pagination** - Page navigation
- **InfiniteScroll** - Infinite scroll loading

### Feedback Components

- **Toast** - Toast notifications
- **Alert** - Alert messages
- **Modal** - Modal dialogs
- **Confirm** - Confirmation dialogs
- **Tooltip** - Hover tooltips

## 🎨 Theme Customization

Adnaan UI uses CSS variables for theming. **The library does NOT override your project's theme variables**, allowing seamless integration with existing theme systems.

### Define Your Theme

Simply define CSS variables in your project - the UI components will automatically use them:

```css
:root {
  /* Primary theme colors */
  --accent-color: #3b82f6;
  --primary-color: #3b82f6;  /* Alternative name */
  
  /* Background colors */
  --bg-primary: #ffffff;
  --bg-secondary: #f8fafc;
  
  /* Text colors */
  --text-primary: #1e293b;
  --text-secondary: #64748b;
  
  /* State colors */
  --success-color: #10b981;
  --error-color: #ef4444;
  --warning-color: #f59e0b;
  --info-color: #3b82f6;
  
  /* Other */
  --border-color: #e2e8f0;
  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
  /* ... more variables */
}

[data-theme='dark'] {
  --bg-primary: #0f172a;
  --text-primary: #f1f5f9;
  /* ... more variables */
}
```

### Using Custom Theme Generator

If you're using a custom theme generation tool, simply override the CSS variables:

```tsx
// Apply your generated theme
document.documentElement.style.setProperty('--accent-color', yourAccentColor);
document.documentElement.style.setProperty('--bg-primary', yourBgColor);
// ... etc
```

## 📖 API Examples

### Components API

```tsx
import { Button, Input, Toast, ToastProvider } from 'adnaan-ui';

<Button 
  variant="primary" 
  size="large" 
  isLoading={loading}
  onClick={handleClick}
>
  Submit
</Button>

// Toast requires ToastProvider
<ToastProvider>
  <App />
</ToastProvider>
```

### Global UI API

```tsx
// Toast
adnaan.toast.success('Success message');
adnaan.toast.error('Error message');
adnaan.toast.info('Info message');
adnaan.toast.warning('Warning message');

// Modal
adnaan.modal.show(
  <div>Modal Content</div>,
  { title: 'My Modal', size: 'large' }
);

const confirmed = await adnaan.modal.confirm({
  title: 'Delete Item',
  message: 'Are you sure you want to delete this item?',
  confirmText: 'Delete',
  confirmVariant: 'danger',
});

// Alert
adnaan.alert.info('This is an info alert');

// Tooltip
adnaan.tooltip.show(event.target, 'Tooltip content');
```

### Direct Import

```tsx
import { toast, modal } from 'adnaan-ui';

toast.success('Success!');
modal.confirm({ message: 'Confirm?' });
```

## 🔧 Utilities

```tsx
import { scrollLock } from 'adnaan-ui/utils';

// Lock scroll
scrollLock.lock();

// Unlock scroll
scrollLock.unlock();
```

## 📝 TypeScript

Full TypeScript support with type definitions:

```tsx
import type { ButtonProps, ModalOptions } from 'adnaan-ui';

const buttonConfig: ButtonProps = {
  variant: 'primary',
  size: 'medium',
  isLoading: false,
};

const modalConfig: ModalOptions = {
  title: 'My Modal',
  size: 'medium',
  closeOnOverlayClick: true,
};
```

## 🌐 Browser Support

- Chrome >= 90
- Firefox >= 88
- Safari >= 14
- Edge >= 90

## 📄 License

This project is licensed under the [Mozilla Public License 2.0](LICENSE).

## 🤝 Contributing

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

## 📮 Support

If you have any questions or issues, please open an issue on GitHub.

---

<div align="center">
Made with ❤️ by Adnaan
</div>

adnaan/React UI组件库

简介

发行版 (1)

贡献者

语言

近期动态

adnaan/React UI组件库 .gitee-modal { width: 500px !important; }

简介

发行版 (1)

贡献者

语言

近期动态

搜索帮助

adnaan/React UI组件库