# react-auto-skeleton

**Repository Path**: wdcodecn/react-auto-skeleton

## Basic Information

- **Project Name**: react-auto-skeleton
- **Description**: react-auto-skeleton
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-01
- **Last Updated**: 2025-10-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# react-auto-skeleton

🎨 Automatic skeleton screen system for React - Transform HTML tags into skeleton components during loading, zero configuration required.

[![npm version](https://badge.fury.io/js/react-auto-skeleton.svg)](https://badge.fury.io/js/react-auto-skeleton)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## ✨ Features

- 🚀 **Zero Configuration** - Wrap your content with `SkeletonProvider`, it automatically converts HTML tags
- 🎯 **Smart Tag Recognition** - Automatically identifies content tags (h1-h6, p, span, img, button, etc.) and skips layout tags (div, section, etc.)
- ⚡ **Performance Optimized** - Nested provider detection, useMemo caching, React key preservation
- 🎨 **Highly Customizable** - Support for custom widths, heights, counts, and circular skeletons
- 🔧 **TypeScript Support** - Full type definitions included
- 📦 **Lightweight** - Built on top of `react-loading-skeleton`
- ♿ **Accessible** - Maintains original HTML structure and styles

## 📦 Installation

```bash
npm install react-auto-skeleton
# or
yarn add react-auto-skeleton
# or
pnpm add react-auto-skeleton
```

**Note:** `react-loading-skeleton` is a peer dependency and will be installed automatically. The CSS is automatically imported when you use the package.

## 🚀 Quick Start

Simply import and use - no additional CSS imports needed:

```tsx
import { SkeletonProvider } from 'react-auto-skeleton';

function UserCard() {
  const [loading, setLoading] = useState(true);

  return (
    <SkeletonProvider loading={loading}>
      <div className="card">
        <img src="avatar.jpg" className="avatar" />
        <h3>John Doe</h3>
        <p>Software Engineer</p>
        <button>Follow</button>
      </div>
    </SkeletonProvider>
  );
}
```

That's it! When `loading={true}`, all content tags automatically show skeletons.

### Optional: Theme Customization

Wrap your app with `SkeletonTheme` for global styling:

```tsx
import { SkeletonTheme } from 'react-auto-skeleton';

function App() {
  return (
    <SkeletonTheme baseColor="#e0e0e0" highlightColor="#f5f5f5">
      <YourApp />
    </SkeletonTheme>
  );
}
```

### 2. Use SkeletonProvider

```tsx
import { SkeletonProvider } from 'react-auto-skeleton';

function UserCard() {
  const [loading, setLoading] = useState(true);

  return (
    <SkeletonProvider loading={loading}>
      <div className="card">
        <img src="avatar.jpg" className="avatar" />
        <h3>John Doe</h3>
        <p>Software Engineer</p>
        <button>Follow</button>
      </div>
    </SkeletonProvider>
  );
}
```

That's it! When `loading={true}`, all content tags automatically show skeletons.

## 📖 Advanced Usage

### Custom Skeleton Dimensions

Use `data-skeleton-*` attributes to customize individual elements:

```tsx
<SkeletonProvider loading={loading}>
  <div>
    <img
      src="avatar.jpg"
      data-skeleton-width={64}
      data-skeleton-height={64}
      data-skeleton-circle
    />
    <h3 data-skeleton-width={200}>Title</h3>
    <p data-skeleton-count={3}>Long text content...</p>
  </div>
</SkeletonProvider>
```

### Available Attributes

- `data-skeleton-width` - Width in pixels or percentage
- `data-skeleton-height` - Height in pixels
- `data-skeleton-count` - Number of skeleton lines (for text)
- `data-skeleton-circle` - Boolean, render circular skeleton

### Default Widths

The library comes with smart defaults for each HTML tag:

| Tag Type | Default Width |
|----------|---------------|
| h1 | 300px |
| h2 | 250px |
| h3 | 200px |
| p | 100% |
| span | 60px |
| button | 80px |
| img | 64px |

You can customize these in `SKELETON_DEFAULT_WIDTHS`.

### Nested Providers

Multiple independent loading states:

```tsx
function Page() {
  return (
    <div>
      <SkeletonProvider loading={headerLoading}>
        <Header />
      </SkeletonProvider>

      <SkeletonProvider loading={contentLoading}>
        <Content />
      </SkeletonProvider>

      <SkeletonProvider loading={footerLoading}>
        <Footer />
      </SkeletonProvider>
    </div>
  );
}
```

Nested providers are automatically detected and skipped to avoid redundant transformations.

### Manual Skeleton Components

You can also use skeleton components directly:

```tsx
import { H3, P, Button } from 'react-auto-skeleton';

function Card({ loading, data }) {
  if (loading) {
    return (
      <div>
        <H3 loading skeletonWidth={200} />
        <P loading skeletonCount={2} />
        <Button loading />
      </div>
    );
  }

  return (
    <div>
      <h3>{data.title}</h3>
      <p>{data.description}</p>
      <button>Click me</button>
    </div>
  );
}
```

## 🎯 Supported HTML Tags

### Automatically Converted Tags

Content tags that are automatically converted to skeletons:

- **Headings**: h1, h2, h3, h4, h5, h6
- **Text**: p, span, label, a, strong, em, b, i, small, mark, code, pre, blockquote, cite, time
- **Form**: button, input, textarea, select
- **Table**: td, th, dt, dd
- **Media**: img

### Preserved Layout Tags

These tags are NOT converted (children are still processed):

- div, section, article, header, footer, nav, aside, main
- ul, ol, li

## 🔧 API Reference

### `<SkeletonProvider>`

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| loading | boolean | Yes | Whether to show skeletons |
| children | ReactNode | Yes | Content to transform |

### `<SkeletonTheme>`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| baseColor | string | - | Base color of skeleton |
| highlightColor | string | - | Highlight color for animation |
| borderRadius | string \| number | - | Border radius |
| duration | number | - | Animation duration in seconds |

### `useSkeletonLoading()`

Hook to access the current loading state from context:

```tsx
import { useSkeletonLoading } from 'react-auto-skeleton';

function Component() {
  const { loading } = useSkeletonLoading();
  return <div>{loading ? 'Loading...' : 'Loaded'}</div>;
}
```

## 🎨 Styling

The CSS is automatically imported when you use the package. No additional setup needed!

For dark mode support, use CSS variables:

```css
:root {
  --skeleton-base: #f0f0f0;
  --skeleton-highlight: #f8f8f8;
}

.dark {
  --skeleton-base: #2a2a2a;
  --skeleton-highlight: #3a3a3a;
}
```

The `SkeletonTheme` component will automatically read these CSS variables and update colors when the theme changes.

## 🤝 Contributing

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

## 📄 License

MIT © [Your Name]

## 🙏 Acknowledgments

Built with [react-loading-skeleton](https://github.com/dvtng/react-loading-skeleton)