npm package: @gulibs/react-shimmer
Description: [English](#english) | [中文](#chinese)
Latest version: 0.0.3

# @gulibs/react-shimmer

[English](#english) | [中文](#chinese)

---

## English

A React component library for creating shimmer loading effects.

### Prerequisites

This library requires **Tailwind CSS** to be installed and configured in your project.

### Installation

```bash
# Install the library
pnpm add @gulibs/react-shimmer

# Install peer dependencies
pnpm add react react-dom tailwindcss
```

### Configuration

#### Configure Tailwind CSS

```javascript
// tailwind.config.js
export default {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@gulibs/react-shimmer/dist/**/*.js'
  ],
  // No additional configuration needed - styles are automatically injected
}
```

> 💡 **Note**: The library automatically injects its CSS styles, so no manual CSS imports are required.

### Usage

```tsx
import { Shimmer } from '@gulibs/react-shimmer'
// No need to manually import CSS, styles are automatically inlined

function App() {
  return (
    <div>
      {/* Text shimmer */}
      <Shimmer type="text">
        <h1>Loading...</h1>
      </Shimmer>

      {/* Content shimmer */}
      <Shimmer type="content">
        <img src="placeholder.jpg" alt="Loading" />
      </Shimmer>

      {/* Custom shimmer with different settings */}
      <Shimmer
        type="text"
        bandWidth="15%"
        duration="3s"
        gradientColors="#ffffffaa"
      >
        <p>Custom shimmer effect</p>
      </Shimmer>
    </div>
  )
}
```

### Examples

#### Text Shimmer

```tsx
<Shimmer type="text" className="text-2xl font-bold">
  Loading content...
</Shimmer>
```

#### Content Shimmer

```tsx
<Shimmer type="content">
  <div className="w-64 h-32 bg-gray-200 rounded-lg">
    <div className="p-4">
      <div className="h-4 bg-gray-300 rounded mb-2"></div>
      <div className="h-4 bg-gray-300 rounded w-3/4"></div>
    </div>
  </div>
</Shimmer>
```

#### Custom Configuration

```tsx
<Shimmer
  type="content"
  angle="90deg"
  bandWidth="5%"
  duration="1.5s"
  direction="left"
  gradientColors={["#ffffff00", "#ffffff88", "#ffffff00"]}
>
  <div className="w-48 h-24 bg-blue-100 rounded"></div>
</Shimmer>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `React.ReactNode` | - | Content to apply shimmer effect to |
| `type` | `"text" \| "content"` | `"text"` | Type of shimmer effect |
| `angle` | `string` | `"45deg"` | Angle of the shimmer gradient |
| `duration` | `string` | `"2.5s"` | Animation duration |
| `gradientColors` | `string \| string[]` | `"#ffffff88"` | Gradient colors |
| `bandWidth` | `string` | `"8%"` | Width of the shimmer band |
| `easing` | `string` | `"ease-in-out"` | Animation easing function |
| `direction` | `"left" \| "right"` | `"right"` | Direction of the shimmer |
| `delay` | `string` | `"0s"` | Animation delay |

### Troubleshooting

#### Shimmer effect not working?

1. **Check Tailwind CSS installation**: Make sure Tailwind CSS is properly installed and configured
2. **Check Tailwind config**: Make sure the library path is included in your `content` array
3. **Browser console**: Check for any CSS injection errors in the browser console
4. **Verify peer dependencies**: Ensure `react`, `react-dom`, and `tailwindcss` are installed

#### Common issues:

- **No shimmer animation**: Tailwind CSS not configured or missing animations
- **Styles not loading**: Tailwind CSS not properly configured in your project
- **TypeScript errors**: Make sure to install the library with proper types
- **CSS injection errors**: Check browser console for any style injection issues

### Development

```bash
# Install dependencies
pnpm install

# Build the library
pnpm run build

# Start development server
pnpm run dev
```

### License

MIT

---

## Chinese

一个用于创建闪烁加载效果的 React 组件库。

### 前置要求

此库需要您的项目中安装并配置 **Tailwind CSS**。

### 安装

```bash
# 安装库
pnpm add @gulibs/react-shimmer

# 安装对等依赖
pnpm add react react-dom tailwindcss
```

### 配置

#### 配置 Tailwind CSS

```javascript
// tailwind.config.js
export default {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@gulibs/react-shimmer/dist/**/*.js'
  ],
  // 无需额外配置 - 样式会自动注入
}
```

> 💡 **注意**: 库会自动注入其 CSS 样式，因此无需手动导入 CSS。

### 使用方法

```tsx
import { Shimmer } from '@gulibs/react-shimmer'
// 无需手动导入 CSS，样式已自动内联

function App() {
  return (
    <div>
      {/* 文本闪烁 */}
      <Shimmer type="text">
        <h1>加载中...</h1>
      </Shimmer>

      {/* 内容闪烁 */}
      <Shimmer type="content">
        <img src="placeholder.jpg" alt="加载中" />
      </Shimmer>

      {/* 自定义闪烁效果 */}
      <Shimmer
        type="text"
        bandWidth="15%"
        duration="3s"
        gradientColors="#ffffffaa"
      >
        <p>自定义闪烁效果</p>
      </Shimmer>
    </div>
  )
}
```

### 示例

#### 文本闪烁

```tsx
<Shimmer type="text" className="text-2xl font-bold">
  加载内容中...
</Shimmer>
```

#### 内容闪烁

```tsx
<Shimmer type="content">
  <div className="w-64 h-32 bg-gray-200 rounded-lg">
    <div className="p-4">
      <div className="h-4 bg-gray-300 rounded mb-2"></div>
      <div className="h-4 bg-gray-300 rounded w-3/4"></div>
    </div>
  </div>
</Shimmer>
```

#### 自定义配置

```tsx
<Shimmer
  type="content"
  angle="90deg"
  bandWidth="5%"
  duration="1.5s"
  direction="left"
  gradientColors={["#ffffff00", "#ffffff88", "#ffffff00"]}
>
  <div className="w-48 h-24 bg-blue-100 rounded"></div>
</Shimmer>
```

### 属性

| 属性 | 类型 | 默认值 | 描述 |
|------|------|---------|-------------|
| `children` | `React.ReactNode` | - | 要应用闪烁效果的内容 |
| `type` | `"text" \| "content"` | `"text"` | 闪烁效果类型 |
| `angle` | `string` | `"45deg"` | 闪烁渐变的角度 |
| `duration` | `string` | `"2.5s"` | 动画持续时间 |
| `gradientColors` | `string \| string[]` | `"#ffffff88"` | 渐变颜色 |
| `bandWidth` | `string` | `"8%"` | 闪烁带的宽度 |
| `easing` | `string` | `"ease-in-out"` | 动画缓动函数 |
| `direction` | `"left" \| "right"` | `"right"` | 闪烁方向 |
| `delay` | `string` | `"0s"` | 动画延迟 |

### 故障排除

#### 闪烁效果不工作？

1. **检查 Tailwind CSS 安装**: 确保 Tailwind CSS 已正确安装和配置
2. **检查 Tailwind 配置**: 确保库路径包含在您的 `content` 数组中
3. **浏览器控制台**: 检查是否有 CSS 注入错误
4. **验证对等依赖**: 确保安装了 `react`、`react-dom` 和 `tailwindcss`

#### 常见问题：

- **无闪烁动画**: Tailwind CSS 未配置或缺少动画
- **样式未加载**: 项目中 Tailwind CSS 配置不正确
- **TypeScript 错误**: 确保使用正确的类型安装库
- **CSS 注入错误**: 检查浏览器控制台中的样式注入问题

### 开发

```bash
# 安装依赖
pnpm install

# 构建库
pnpm run build

# 启动开发服务器
pnpm run dev
```

### 许可证

MIT