React Loaded

> Loading should feel loaded before it actually loads.

Smart skeleton screens that mirror your actual components. No layout shift. No visual jumps.

The Problem

Traditional skeleton screens create a disconnect between loading and loaded states:

- Generic gray boxes do not match your actual UI
- Lists show arbitrary counts (3 skeletons -> 47 items = jarring jump)
- Building custom skeletons for every component is tedious and fragile

The Solution

React Loaded renders your real components in "skeleton mode" using CSS masking. The skeleton is your component, just with content hidden. This guarantees:

- Zero layout shift between loading and loaded states
- Pixel-perfect structure that matches the final render
- Persistent list counts that remember how many items to show

Installation

``bash
pnpm add react-loaded
`

Required: import the stylesheet once in your app:

`tsx
import "react-loaded/style.css";
`

Quick Start

$3

`tsx
import { SmartSkeleton } from "react-loaded";

function UserProfile({ userId }) {
const { data: user, isLoading } = useQuery(["user", userId], fetchUser);

return (
loading={isLoading}
element={}
>


);
}
`

Or with conditional rendering:

`tsx
if (isLoading) {
return (
loading
element={}
/>
);
}

return ;
`

$3

`tsx
import { SmartSkeletonList } from "react-loaded";

function ProductList() {
const { data: products, isLoading } = useQuery(["products"], fetchProducts);

return (
loading={isLoading}
items={products}
storageKey="product-list"
defaultCount={6}
renderItem={(product) => }
renderSkeleton={(index) => (

)}
keyExtractor={(product) => product.id}
/>
);
}
`

How persistence works:
1. First visit: shows defaultCount skeletons (6)
2. Data loads: renders 42 products, saves count to localStorage
3. Next visit: shows 42 skeletons -> loads 42 products -> no jump

API Reference

$3

Wraps a single component to display it in skeleton mode while loading.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| element | ReactElement | required | The skeleton version with mock or placeholder data |
| children | ReactElement | - | The real content when loaded. Returns null if omitted |
| loading | boolean | false | Whether to show the skeleton |
| animate | boolean | true | Enable shimmer animation |
| variant | "filled" \| "ghost" | "filled" | Skeleton background style (ghost disables wrapper/card background) |
| className | string | - | Additional CSS classes |
| seed | string \| number | - | Stable seed for text width randomness |
| suppressRefWarning | boolean | false | Suppress console warning when auto-wrapper is needed |

$3

Renders a list with skeleton placeholders and optional count persistence.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| items | T[] | undefined | required | Array of items, undefined while loading |
| renderItem | (item: T, index: number) => ReactElement | required | Render function for loaded items |
| renderSkeleton | (index: number) => ReactElement | required | Render function for skeleton placeholders |
| loading | boolean | false | Whether to show skeletons |
| storageKey | string | - | localStorage key for count persistence |
| defaultCount | number | 3 | Initial skeleton count |
| minCount | number | 1 | Minimum skeletons to display |
| maxCount | number | - | Maximum skeletons to display |
| animate | boolean | true | Enable shimmer animation |
| variant | "filled" \| "ghost" | "filled" | Skeleton background style for each list placeholder |
| seed | string \| number | - | Stable seed for text width randomness |
| suppressRefWarning | boolean | false | Suppress console warning when auto-wrapper is needed |
| keyExtractor | (item: T, index: number) => string | number | index | Extract unique key for each item |

$3

Hook to detect if a component is rendered inside a skeleton.

`tsx
import { useIsSkeletonMode } from "react-loaded";

function Avatar({ src }) {
const isSkeleton = useIsSkeletonMode();

// Skip expensive operations during skeleton render
if (isSkeleton) {
return