Package Exports

react-ez-skeleton

Readme

react-ez-skeleton

Simple. Accessible. Zero-config React skeletons.

react-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.

No CSS imports. No heavy dependencies. No surprises.

Why react-ez-skeleton?

Zero configuration: works immediately
SSR & hydration safe: Next.js, Remix, etc.
Accessible by default: aria-hidden
Reduced-motion friendly: respects prefers-reduced-motion
Themeable: via CSS variables
Test-friendly: dataTestId -> data-testid
Tiny API: no lock-in

Installation

npm install react-ez-skeleton

yarn add react-ez-skeleton

Quick Start

import { Skeleton } from "react-ez-skeleton";

export function CardLoading() {
  return <Skeleton width={200} height={20} />;
}

That’s it.

No CSS imports
No providers
No setup

Components

`Skeleton`

The base building block.

<Skeleton width={120} height={16} />
<Skeleton width="100%" height={24} radius={8} />

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

`SkeletonText`

Perfect for paragraphs and content blocks.

<SkeletonText lines={3} />

Advanced usage:

<SkeletonText
  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).

`SkeletonCircle`

Ideal for avatars and icons.

<SkeletonCircle size={40} />

Theming (DX Highlight)

No theme providers. No props explosion.

Just CSS variables:

: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

<Skeleton animate={false} />

Testing Support

<Skeleton dataTestId="profile-loading" />

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:

<Skeleton injectStyles={false} />

Then provide your own 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

Final note: react-ez-skeleton is designed for developers who care about correctness, accessibility, and simplicity — without sacrificing control.