What react-content-loader does — and when to use it

react-content-loader is a tiny React library that renders lightweight SVG placeholders (skeleton loaders) while your real content is loading. Instead of a spinner, a skeleton gives users perceptual progress and reduces layout shift by matching the eventual UI dimensions and rhythm.

This is ideal for lists, cards, tables, and complex repetitive UIs where showing grey blocks (or brand-colored placeholders) improves perceived performance. It pairs well with data-fetching libraries and Suspense fallbacks to create a polished loading experience.

Think of it as a composable SVG toolkit: you create a skeleton that mirrors your final layout using rect, circle, and path, then animate a subtle gradient across it. The result feels fast and intentional.

Installation & setup (getting started)

To install, use npm or yarn. If you’re using TypeScript, install types when needed and ensure your bundler supports inline SVG components.

npm install react-content-loader
# or
yarn add react-content-loader

Import the main component into your React file:

import ContentLoader from 'react-content-loader'

Server-side rendering (SSR) and frameworks like Next.js: the component renders pure SVG (no window-dependent code). If you manipulate DOM or window in your own custom SVG logic, guard it behind feature checks. For TypeScript, add ambient types or community type packages if necessary.

Core API and common props

The library exposes a single composable component: ContentLoader. Core props you’ll use every day are width, height, speed, primaryColor, secondaryColor, and uniqueKey (useful for SSR/hydration).

Under the hood you place SVG shapes as children. The loader maps gradient animation across the shapes automatically — so you only need to design the skeleton, not the animation.

Example basic loader:

import ContentLoader from 'react-content-loader'

const CardSkeleton = () => (
  <ContentLoader width={400} height={160} speed={1.5}
    primaryColor="#f3f3f3" secondaryColor="#ecebeb">
    <rect x="0" y="0" rx="6" ry="6" width="400" height="80" />
    <circle cx="40" cy="120" r="20" />
    <rect x="70" y="105" rx="4" ry="4" width="300" height="14" />
  </ContentLoader>
)

Custom SVG skeletons & the Facebook loader style

Want the familiar Facebook-style skeleton? Compose rounded rectangles and circles to mimic avatars, titles, and meta rows. The visual trick is spacing and corner radii, not complex paths. Keep shapes simple for perf.

If you have an existing SVG mock, you can paste it inside ContentLoader and adapt attributes like viewBox, width, and height. For complex UIs, break the skeleton into small components (AvatarSkeleton, RowSkeleton) and compose them.

Example: Facebook-like row:

<ContentLoader speed={2} width={400} height={70}
  primaryColor="#f6f7f8" secondaryColor="#edeef1">
  <circle cx="35" cy="35" r="30" />
  <rect x="75" y="13" rx="4" ry="4" width="300" height="13" />
  <rect x="75" y="35" rx="3" ry="3" width="250" height="10" />
</ContentLoader>

Pro tip: use consistent spacing and baseline widths across list items to avoid a “jumpy” skeleton experience when items render.

Performance and accessibility best practices

Keep SVG node counts low. Hundreds of small SVG elements animate continuously and increase CPU/GPU work. If you need a long list skeleton, render a small number of skeleton rows and reuse them (or virtualize your list), instead of rendering placeholders for every item.

Respect user preferences: check prefers-reduced-motion in CSS or JS and reduce or disable the shimmer animation when it’s set. The library doesn’t automatically detect this for you, so wrap loaders with a hook or style check.

Accessibility: mark purely decorative loaders with aria-hidden="true". If a loader provides meaningful context (e.g., “loading comment list”), use an accessible label or offscreen readable text so screen reader users know content is pending.

Advanced patterns and examples

Adaptive skeletons: generate skeleton shapes dynamically from layout metadata. For example, if your API returns item counts or a template definition, build shapes programmatically to match that structure — no hardcoding required.

Suspense integration: use ContentLoader as a Suspense fallback. When coupled with data-fetching hooks, you get automatic transitions from skeleton to content. For lists, display a fixed-height skeleton container to prevent layout shifts.

Visual consistency is key: reuse color variables for primaryColor and secondaryColor that match your design system. Slightly faster shimmer speeds help simulate data arriving quickly, but don’t make it jittery.

Troubleshooting and common issues

SVG not animating in some browsers: check for CSS that disables animations or user system settings that enforce reduced motion. Also ensure you don’t accidentally override inline SVG styles with global CSS resets.

Hydration mismatch warnings: use uniqueKey or explicit SSR-safe rendering to avoid different SVG markup between server and client. For deterministic output, avoid random IDs in the SVG unless you seed them consistently.

Colors or scaling look off: confirm the viewBox and element coordinates align with the declared width/height. Using percentage widths or responsive layouts may require explicit preserveAspectRatio tuning.

Examples & resources

Hands-on tutorials and example collections are useful when you want ready-made patterns. For an advanced walkthrough, see this advanced skeleton tutorial on Dev.to: advanced skeleton loaders with react-content-loader.

For the official repo and additional examples, the project homepage and examples are a great reference: react-content-loader GitHub. Also check the package page on npm for the latest installation notes.

Sample pattern idea: create a <ListSkeleton count={5} /> component that maps a small number of skeleton rows and accepts variants (compact, dense, card) to keep one implementation and many visual uses.

Conclusion — a checklist before production

Before shipping: verify SSR consistency, limit SVG complexity, respect reduced-motion preferences, and add accessible labels or aria-hidden where appropriate. Test on low-end devices to ensure the shimmer doesn’t tax the CPU.

react-content-loader gives you the building blocks for polished placeholders. With a few patterns and attention to accessibility and performance, it turns a blank loading state into a thoughtful user experience.

Need deeper examples? Start with the tutorial link above and the GitHub examples, then adapt skeletons to your design tokens and spacing system for a consistent result.

FAQ

How do I install react-content-loader?

Install with npm i react-content-loader or yarn add react-content-loader, import ContentLoader, and use it in your components. For TypeScript, add types if necessary and ensure your bundler supports inline SVG usage.

How can I create a custom SVG skeleton with react-content-loader?

Compose SVG shapes (rect, circle, path) inside ContentLoader. Tune width, height, primaryColor, secondaryColor, and place shapes to mirror your final UI layout. You can paste an existing SVG and adapt coordinates.

What are the best practices for performance and accessibility?

Keep SVG nodes minimal, virtualize or reuse skeletons for long lists, honor prefers-reduced-motion, and use aria-hidden or readable labels for assistive tech. Test on low-power devices and browsers to validate performance.

Semantic core (keyword clusters)

Primary keywords:
- react-content-loader
- React skeleton loader
- react-content-loader tutorial
- React placeholder loading
- react-content-loader installation
- React SVG skeleton
- react-content-loader example
- React loading placeholder
- react-content-loader setup
- React Facebook loader

Secondary / intent-based queries:
- react-content-loader customization
- React skeleton pattern
- react-content-loader SVG
- React loading library
- react-content-loader getting started
- how to customize react-content-loader
- react-content-loader performance
- react-content-loader SSR
- react-content-loader typescript

Clarifying / long-tail and LSI:
- react content loader examples for lists
- react skeleton loader for cards
- create custom svg skeleton react
- facebook style loader react
- react-content-loader speed primaryColor secondaryColor
- prefers-reduced-motion react loaders
- accessible skeleton loader react
- react-content-loader npm install
- react-content-loader github repo
  

Backlinks & further reading

Advanced tutorial and examples: advanced skeleton loaders with react-content-loader.

Official repository and example gallery: react-content-loader GitHub.