React Loadly

Reliable React Loading Experience Toolkit

Modern Loaders • Skeletonize • Skeletons • Loading Hooks • Accessibility • SSR Support

📦 NPM • 🌐 Showcase • 📖 Documentation • 🐛 Issues

---

🇵🇸 This project stands with Palestine — freedom, dignity, and justice.

---

Looking for installation guides, examples, loaders, skeleton patterns, and documentation?

Visit the official showcase:

https://mostafashadow1.github.io/react-loadly/

---

About

React Loadly is a modern loading experience toolkit for React applications.

It provides:

• Production-ready loaders
• Skeletonize: your real component becomes its own skeleton
• SkeletonLoader
• SkeletonGroupLoader
• Loading state hooks
• Accessibility support
• Reduced motion support
• SSR compatibility
• React 17 / 18 / 19 support
• Next.js 14 / 15 / 16 support

Designed for dashboards, SaaS products, admin panels, forms, data-heavy applications, and modern user interfaces.

---

When to use React Loadly

• A component fetches data and needs a skeleton or spinner while it loads.
• You want a skeleton that matches your real component exactly, without writing a second skeleton layout (Skeletonize).
• You want one component that switches between loading, error, empty and content (SkeletonSwitchLoader).
• You need accessible loaders (role="status", aria-label, reduced motion) without writing CSS animations.
• You need a fullscreen or page-level loader, or a Suspense / next/dynamic fallback.

Not for: Progress bars for route changes at the top of the page (use nprogress or the router's own indicator).

Using an AI coding agent? This package ships an AGENTS.md and an llms.txt with usage rules and examples. Agents with the Context7 MCP can fetch these docs directly.

---

Skeletonize (new in 3.1)

Stop writing a second skeleton layout for every component. Wrap the real component, render it with placeholder data, and it becomes its own skeleton while loading.

import { Skeletonize } from "react-loadly";

const placeholderUser = { name: "Loading name", role: "Loading role", avatar: "" };

export function Profile() {
  const { data, isLoading } = useQuery({ queryKey: ["user"], queryFn: getUser });

  return (
    <Skeletonize loading={isLoading}>
      <UserCard user={data ?? placeholderUser} />
    </Skeletonize>
  );
}

• Pixel-perfect by design: the skeleton is your real component, so it always matches the layout, spacing and sizes.
• No sync work: change the component and the skeleton changes with it.
• Works with anything: hooks, context, data fetching, Tailwind, CSS Modules and plain CSS.
• Text, images, icons and form controls become skeleton blocks; containers keep their background, borders and padding. Add data-skeleton to any other element to turn it into a block.
• Accessible: content is inert and aria-hidden while loading, and screen readers hear one role="status" message (loadingLabel).
• Animations: shimmer, wave, pulse or none, with shimmer aligned across every block; respects prefers-reduced-motion.
• Theming: baseColor, highlightColor and speed props, or inherit them from SkeletonGroupLoader.
• SSR and Next.js App Router ready, and children keep their state when loading toggles.

Live examples · Full docs

Also in 3.1: the package is smaller, with 28 files instead of 972 (about 1 MB unpacked instead of 1.5 MB).

---

Quick Start

Install React Loadly:

npm install react-loadly

pnpm add react-loadly

yarn add react-loadly

Import the styles:

import "react-loadly/styles.css";

Example:

import { PulseLoader } from "react-loadly";
import "react-loadly/styles.css";

export default function App() {
  return <PulseLoader />;
}

---

Monorepo Structure

This repository uses a pnpm monorepo architecture.

react-loadly
├── packages
│   └── react-loadly
│
└── apps
    └── showcases

Packages

Package	Description
packages/react-loadly	Published npm package
apps/showcases	Documentation, examples, and GitHub Pages showcase

---

Project Links

📦 NPM Package

https://www.npmjs.com/package/react-loadly

🌐 Showcase & Documentation

https://mostafashadow1.github.io/react-loadly/

📖 Package Source

https://github.com/Mostafashadow1/react-loadly/tree/main/packages/react-loadly

🐛 Report Issues

https://github.com/Mostafashadow1/react-loadly/issues

🤝 Pull Requests

https://github.com/Mostafashadow1/react-loadly/pulls

---

For Contributors

React Loadly follows a simple rule:

Whenever a loader, skeleton, hook, prop, or feature changes inside:

packages/react-loadly

the showcase must be updated as well:

apps/showcases

The showcase is considered the source of truth for:

• Documentation
• Examples
• Usage patterns
• New feature demonstrations

---

Local Development

Install dependencies:

pnpm install

Run showcase:

pnpm dev

Build everything:

pnpm build

Type checking:

pnpm type-check

Run tests:

pnpm test

---

Documentation

For full documentation, component APIs, examples, skeleton patterns, hooks, and production guides, visit:

🌐 https://mostafashadow1.github.io/react-loadly/

Or browse the package documentation directly:

📖 https://github.com/Mostafashadow1/react-loadly/tree/main/packages/react-loadly

---

License

MIT License

---

Built with ❤️ by Shadow Coding