react-ez-skeleton provides simple, flexible skeleton components for React applications, enabling fast setup and smooth loading states without unnecessary complexity.
npm install react-ez-skeletonreact-ez-skeleton is a lightweight React skeleton loader library focused on excellent developer experience (DX). It works out of the box, is SSR-safe, respects accessibility and motion preferences, and is easy to theme using CSS variables.
aria-hidden
prefers-reduced-motion
dataTestId -> data-testid
bash
npm install react-ez-skeleton
`
or
`bash
yarn add react-ez-skeleton
`
Quick Start
`tsx
import { Skeleton } from "react-ez-skeleton";
export function CardLoading() {
return ;
}
`
That’s it.
- No CSS imports
- No providers
- No setup
Components
$3
The base building block.
`tsx
`
#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| width | number \| string | "100%" | Width (px, %, etc.) |
| height | number \| string | 16 | Height |
| radius | number \| string | 4 | Border radius |
| animate | boolean | true | Enable shimmer animation |
| respectReducedMotion | boolean | true | Respects OS motion settings |
| ariaHidden | boolean | true | Decorative by default |
| injectStyles | boolean | true | Auto-inject required styles |
| dataTestId | string | — | Adds data-testid |
| className | string | — | Custom class |
| style | React.CSSProperties | — | Inline styles |
$3
Perfect for paragraphs and content blocks.
`tsx
`
Advanced usage:
`tsx
lines={4}
randomizeLineWidths
randomizeMin={60}
randomizeMax={95}
dataTestId="post-skeleton"
/>
`
#### Props (in addition to SkeletonProps)
| Prop | Type | Default |
| --- | --- | --- |
| lines | number | 3 |
| lineHeight | number \| string | 16 |
| gap | number \| string | 8 |
| lineWidths | (number \| string)[] | — |
| randomizeLineWidths | boolean | false |
| randomizeMin | number | 60 |
| randomizeMax | number | 100 |
| randomizeSeed | number | — |
Seeded randomness means deterministic layouts (nice for SSR and tests).
$3
Ideal for avatars and icons.
`tsx
`
Theming (DX Highlight)
No theme providers. No props explosion.
Just CSS variables:
`css
:root {
--ez-skeleton-color-start: #2a2a2a;
--ez-skeleton-color-middle: #3a3a3a;
--ez-skeleton-color-end: #2a2a2a;
}
`
Works automatically across your app.
Perfect for dark mode and design systems.
Accessibility & Motion
- Skeletons are decorative by default
- Automatically hidden from screen readers
- Honors prefers-reduced-motion
`tsx
`
Testing Support
`tsx
expect(screen.getByTestId("profile-loading")).toBeInTheDocument();
`
SkeletonText automatically appends line indexes:
- profile-loading-0
- profile-loading-1
SSR & Framework Support
Fully safe for:
- Next.js (App Router & Pages)
- Remix
- Vite SSR
- Astro
- CRA
Style injection is:
- Singleton-based
- Guarded
- Client-only
- No hydration mismatches
Opt-out Style Injection
If you want full control:
`tsx
`
Then provide your own CSS:
`css
@keyframes react-ez-skeleton-pulse {
from {
background-position: 100% 50%;
}
to {
background-position: 0 50%;
}
}
`
Bundle Philosophy
- No runtime dependencies
- Tree-shakable
- Side-effect safe
- Dual ESM + CJS builds
- TypeScript first
Contributing
PRs and issues are welcome on GitHub.
Please keep changes DX-focused and minimal.
Documentation & Examples
View the full documentation and live examples at react-ez-skeleton-docs.vercel.app.
License
MIT © Md. Shafiul Alam
Final note: react-ez-skeleton` is designed for developers who care about correctness, accessibility, and simplicity — without sacrificing control.