# React Smart Loading Effects

[![npm version](https://img.shields.io/npm/v/react-smart-loading-effects.svg)](https://www.npmjs.com/package/react-smart-loading-effects)
[![bundle size](https://img.shields.io/badge/gzip-2.7%20KB-brightgreen)](https://www.npmjs.com/package/react-smart-loading-effects)
[![TypeScript](https://img.shields.io/badge/TypeScript-ready-blue)](https://www.npmjs.com/package/react-smart-loading-effects)
[![license](https://img.shields.io/npm/l/react-smart-loading-effects.svg)](https://www.npmjs.com/package/react-smart-loading-effects)

**The easiest way to add beautiful React skeleton loaders to your app.**

`react-smart-loading-effects` is a lightweight **React skeleton loader** library with polished **shimmer animation**, zero configuration, and production-ready layouts for the UI patterns you build every day — product cards, data tables, SaaS dashboards, user profiles, notification lists, and article text.

Stop hand-coding dozens of placeholder `<div>` elements. Install once, drop in `<SmartLoader />`, and ship professional **loading skeleton screens** in under 30 seconds.

```bash
npm install react-smart-loading-effects
```

**Peer dependencies:** React 18+ and React DOM 18+

---

## See it in action

![React skeleton loader overview — card, table, dashboard, profile, list, and text shimmer loaders](https://cdn.jsdelivr.net/npm/react-smart-loading-effects@1.0.0/docs/overview-demo.gif)

*Six loader types, one package. GPU-friendly shimmer, accessible defaults, ~2.7 KB gzipped.*

---

## Table of contents

- [Why use this library?](#why-use-this-library)
- [Key features](#key-features)
- [Quick start](#quick-start)
- [Loader demos](#loader-demos)
  - [Card skeleton loader](#card-skeleton-loader)
  - [Table skeleton loader](#table-skeleton-loader)
  - [Dashboard skeleton loader](#dashboard-skeleton-loader)
  - [Profile skeleton loader](#profile-skeleton-loader)
  - [List skeleton loader](#list-skeleton-loader)
  - [Text skeleton loader](#text-skeleton-loader)
- [API reference](#api-reference)
- [Framework support](#framework-support)
- [Accessibility](#accessibility)
- [FAQ](#faq)
- [Local demo](#local-demo)
- [License](#license)

---

## Why use this library?

Most React apps need **loading placeholders** — but building them from scratch is repetitive:

- Card grids need image, title, description, and button skeletons
- Admin panels need table row and column placeholders
- Dashboards need KPI cards, chart areas, and sidebar stubs
- Profile pages need avatar, name, and bio lines
- Feeds need list items with avatars and text
- Articles need multi-line text skeletons

`react-smart-loading-effects` gives you all of this with a single prop:

```tsx
<SmartLoader type="table" rows={10} columns={5} />
```

No CSS imports. No UI framework. No Tailwind dependency. Just beautiful, accessible **React loading states** out of the box.

---

## Key features

- **6 production-ready layouts** — card, table, dashboard, profile, list, text
- **Shimmer animation** — smooth, GPU-accelerated skeleton shimmer (disable with `animated={false}`)
- **Zero configuration** — styles inject automatically on first render
- **Tiny bundle** — ~2.7 KB gzipped (ESM)
- **TypeScript** — full type exports for props and loader types
- **Accessible** — `aria-busy`, `aria-hidden`, and `prefers-reduced-motion` support
- **Next.js ready** — works with App Router, Pages Router, and React Server Components consumers
- **Tree-shakeable** — ESM + CommonJS builds via tsup

---

## Quick start

```tsx
import { SmartLoader } from "react-smart-loading-effects";

function ProductGrid({ loading }: { loading: boolean }) {
  if (loading) {
    return <SmartLoader type="card" />;
  }
  return <ProductCard />;
}
```

Use while data is fetching:

```tsx
{isLoading ? <SmartLoader type="table" rows={8} columns={5} /> : <DataTable data={data} />}
```

---

## Loader demos

### Card skeleton loader

Perfect for **product cards**, blog post previews, e-commerce grids, and service tiles.

![React card skeleton loader with shimmer — image, title, description, and CTA placeholders](https://cdn.jsdelivr.net/npm/react-smart-loading-effects@1.0.0/docs/card-loader.gif)

```tsx
<SmartLoader type="card" />
```

Includes image placeholder (16:9), title bar, description lines, and CTA button skeleton.

---

### Table skeleton loader

Ideal for **admin dashboards**, CRM tables, analytics grids, and any paginated data view.

![React table skeleton loader with shimmer — configurable rows and columns](https://cdn.jsdelivr.net/npm/react-smart-loading-effects@1.0.0/docs/table-loader.gif)

```tsx
<SmartLoader type="table" rows={10} columns={5} />
```

Configurable `rows` and `columns` with a responsive horizontal scroll wrapper.

---

### Dashboard skeleton loader

Built for **SaaS dashboards**, analytics pages, and internal admin tools.

![React dashboard skeleton loader — KPI cards, chart placeholders, and sidebar](https://cdn.jsdelivr.net/npm/react-smart-loading-effects@1.0.0/docs/dashboard-loader.gif)

```tsx
<SmartLoader type="dashboard" />
```

Includes KPI stat cards, two chart panel placeholders, and a sidebar navigation strip.

---

### Profile skeleton loader

Great for **user profile pages**, team directories, and account settings screens.

![React profile skeleton loader — avatar, name, and bio line placeholders](https://cdn.jsdelivr.net/npm/react-smart-loading-effects@1.0.0/docs/profile-loader.gif)

```tsx
<SmartLoader type="profile" />
```

Centered layout with circular avatar, name bar, and multi-line bio placeholders.

---

### List skeleton loader

Use for **notification feeds**, message inboxes, activity streams, and comment lists.

![React list skeleton loader — avatar, title, and subtitle rows](https://cdn.jsdelivr.net/npm/react-smart-loading-effects@1.0.0/docs/list-loader.gif)

```tsx
<SmartLoader type="list" rows={6} />
```

Each row includes a circular avatar, title line, and subtitle line.

---

### Text skeleton loader

Designed for **blog articles**, documentation pages, long-form content, and paragraph loading.

![React text skeleton loader — multi-line content with natural width variation](https://cdn.jsdelivr.net/npm/react-smart-loading-effects@1.0.0/docs/text-loader.gif)

```tsx
<SmartLoader type="text" rows={8} />
```

Multiple text rows with varied widths (100%, 92%, 78%) for a natural reading feel.

---

### Static skeleton (no animation)

Disable shimmer for static placeholders or when you handle animation yourself:

```tsx
<SmartLoader type="card" animated={false} />
```

---

## API reference

### `SmartLoader`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `type` | `"card" \| "table" \| "dashboard" \| "profile" \| "list" \| "text"` | — | Skeleton layout (required) |
| `rows` | `number` | varies | Row count for table, list, and text loaders |
| `columns` | `number` | `4` | Column count for table loader |
| `animated` | `boolean` | `true` | Enable shimmer skeleton animation |
| `width` | `number \| string` | `"100%"` | Container width |
| `height` | `number \| string` | — | Container height |
| `className` | `string` | — | Additional CSS class on loader root |

### Individual loaders

Import loaders directly for finer control:

```tsx
import {
  CardLoader,
  TableLoader,
  DashboardLoader,
  ProfileLoader,
  ListLoader,
  TextLoader,
  Skeleton,
} from "react-smart-loading-effects";

<CardLoader animated />
<TableLoader rows={5} columns={4} />
<Skeleton width={200} height={20} borderRadius={8} />
```

### TypeScript

```tsx
import type { SmartLoaderProps, LoaderType, LoaderCommonProps } from "react-smart-loading-effects";
```

---

## Framework support

| Framework | Support |
|-----------|---------|
| React 18+ | Yes |
| React 19+ | Yes |
| Next.js (App Router) | Yes |
| Next.js (Pages Router) | Yes |
| Vite | Yes |
| Create React App | Yes |

No CSS file imports required — shimmer keyframes are injected automatically when `SmartLoader` mounts.

### Next.js example

```tsx
"use client";

import { SmartLoader } from "react-smart-loading-effects";

export default function Loading() {
  return <SmartLoader type="dashboard" />;
}
```

---

## Accessibility

Built-in accessibility for screen readers and motion preferences:

- Loading root uses `role="status"`, `aria-busy="true"`, and `aria-label="Loading"`
- Decorative skeleton blocks are marked `aria-hidden="true"`
- Shimmer animation respects **`prefers-reduced-motion: reduce`** — users who prefer less motion see static skeletons automatically

---

## FAQ

### What is a React skeleton loader?

A **skeleton loader** (or **skeleton screen**) is a placeholder UI that mimics the shape of content while data loads. Unlike spinners, skeletons reduce perceived wait time by showing users what is coming. `react-smart-loading-effects` provides pre-built skeleton layouts with shimmer animation.

### How is this different from a spinner?

Spinners show activity but not structure. **Skeleton loaders** preview the actual layout — card images, table rows, dashboard charts — so users feel less disoriented during loading.

### Do I need to import CSS?

No. Shimmer styles are injected once on first render. Zero extra setup.

### Does it work with Next.js?

Yes. Use `SmartLoader` in client components (`"use client"`) or in loading.tsx files. No SSR issues — styles inject on the client.

### Can I disable the shimmer animation?

Yes: `<SmartLoader type="card" animated={false} />`. Animation also auto-disables when the user has reduced motion enabled in their OS settings.

### How big is the bundle?

Approximately **2.7 KB gzipped** (ESM). No runtime dependencies beyond React.

### Can I use individual loader components?

Yes. Export `CardLoader`, `TableLoader`, `DashboardLoader`, `ProfileLoader`, `ListLoader`, `TextLoader`, and the base `Skeleton` primitive.

---

## Local demo

Preview all loaders with animation controls:

```bash
npm run build
npm run demo
```

Open [http://localhost:5174](http://localhost:5174).

### Regenerate README GIFs

```bash
npm run build
npm run demo          # keep dev server running
npm run demo:gif      # captures docs/*.gif via Playwright
```

---

## License

MIT