react-zero-skeleton

→ Live demo · Docs

---

The skeleton loader is the first contact between your app and your user. That moment deserves care, not an afterthought maintained in a separate file that drifts from reality the moment you touch the real component.

react-zero-skeleton changes the relationship. The component IS its skeleton. Wrap it once. The library measures the real layout at runtime, generates one bone per element, and keeps everything in sync automatically. Forever.

// Before: two things to write, two things to maintain, two things to break.
function ArticleCard({ article }) { /* real component */ }
const ArticleCardSkeleton = () => ( /* a copy you'll forget to update */ )

// After: one thing.
const ArticleCard = withSkeleton(function ArticleCard({ article }) {
  return (
    <View>
      <Image source={{ uri: article.cover }} style={{ height: 160 }} />
      <Text style={s.title}>{article.title}</Text>
      <Text style={s.excerpt}>{article.excerpt}</Text>
    </View>
  )
})

<ArticleCard hasSkeleton isLoading={isLoading} article={data} />

---

Installation

npm install react-zero-skeleton

No native code. No pod install. No linking.

The bundler resolves the right build automatically:

• React Native / Metro → native build (Fiber walk · onLayout · Animated)
• React web / Next.js / Vite → web build (DOM · ResizeObserver · CSS animations)

---

How it works

On the first render, the component renders invisibly. react-zero-skeleton walks the React Fiber tree (on native) or the DOM (on web), measures every View / Image / Text, and captures position, size, and corner radius. The overlay - one bone per element, positioned exactly - replaces the hidden content until isLoading becomes false.

Layout changes propagate automatically. If you add a field to the card, the skeleton gains a bone. No manual sync required.

---

Quick start

Wrap once

import { withSkeleton } from 'react-zero-skeleton'

function ProfileCard({ user }) {
  return (
    <View style={s.wrap}>
      <Image source={{ uri: user.avatar }} style={s.avatar} />
      <Text style={s.name}>{user.name}</Text>
      <Text style={s.bio}>{user.bio}</Text>
    </View>
  )
}

export default withSkeleton(ProfileCard)

Use it

// Two props. That's it.
<ProfileCard hasSkeleton isLoading={isLoading} user={data} />

// Shorthand: activates hasSkeleton + isLoading at once
<ProfileCard isLoadingSkeleton user={data} />

Global theme

import { SkeletonTheme } from 'react-zero-skeleton'

<SkeletonTheme animation="wave" color="#E0E0E0" highlightColor="#F5F5F5">
  <App />
</SkeletonTheme>

Config priority: skeletonConfig prop > SkeletonTheme > defaults.

---

Animations

Nine animations. Each has a reason to exist.

Animation	Character
pulse	Soft opacity fade. The default. Works everywhere, no dependencies.
wave	Shimmer left to right. Classic and readable.
shiver	Wider, more energetic wave. Good for large image placeholders.
drip	Vertical shimmer sweeping top to bottom, each bone phase-shifted.
slide	Bones drift upward while fading in. A gentle breathing effect.
beat	Double heartbeat: scale + opacity. Ideal for health and real-time data UIs.
shaker	A rapid horizontal tremor burst, then silence. For alert-style states.
shatter	Each bone fragments into a grid of squares. The signature animation.
none	Static placeholder. Useful with prefers-reduced-motion.

// Global
<SkeletonTheme animation="shatter">…</SkeletonTheme>

// Per component
<ProfileCard hasSkeleton isLoading={isLoading} skeletonConfig={{ animation: 'beat' }} />

// Speed
skeletonConfig={{ animation: 'wave', speed: 'slow' }}   // 0.5×
skeletonConfig={{ animation: 'wave', speed: 'rapid' }}  // 2×
skeletonConfig={{ animation: 'wave', speed: 1.5 }}      // custom multiplier

wave and shiver require a LinearGradient peer on React Native: npx expo install expo-linear-gradient or npm install react-native-linear-gradient. On web, CSS gradients are used: no peer needed.

Cascade

When cascade > 0, each bone's animation starts delayed by bone.y × cascade ms, creating a top-to-bottom sequential wave through the component.

<SkeletonTheme animation="pulse" cascade={3}>
  {/* bone at y=0 starts immediately, bone at y=100 starts 300ms later */}
</SkeletonTheme>

Shatter

<ProfileCard
  hasSkeleton
  isLoading={isLoading}
  skeletonConfig={{
    animation: 'shatter',
    shatterConfig: {
      cellSize: 24,        // px - overrides column count
      stagger: 80,         // ms delay between squares
      fadeStyle: 'radial'  // 'random' | 'cascade' | 'radial'
    }
  }}
/>

---

Loading experience

The transition into and out of the skeleton is part of the experience. react-zero-skeleton gives you control over both.

Enter animation

Played when the skeleton first appears.

<SkeletonTheme enter="fadeUp">…</SkeletonTheme>
// 'fade' | 'fadeUp' | 'fadeDown' | 'fadeLeft' | 'fadeRight' | 'none'

Exit animation

Played when the skeleton disappears and content takes over.

<SkeletonTheme animation="shatter" exit="fadeUp" revealOnExit>…</SkeletonTheme>

revealOnExit keeps the real content visible underneath while the skeleton fades out, creating a reveal effect instead of an abrupt swap.

---

SkeletonBox

By default, container divs are skipped: only their text and image children receive bones. When a container is itself a visually meaningful shape (a stat card, a chip, a badge), wrap it with SkeletonBox to emit the box as a semi-transparent bone with its children rendered on top.

import { SkeletonBox } from 'react-zero-skeleton'

function Stat({ label, value }) {
  return (
    <SkeletonBox style={{ flex: 1, backgroundColor: '#eee', borderRadius: 10, padding: 12 }}>
      <Text style={{ width: 'fit-content' }}>{label}</Text>
      <Text style={{ fontWeight: '700', width: 'fit-content' }}>{value}</Text>
    </SkeletonBox>
  )
}

The box bone is always static (no animation). Children animate normally.

---

SkeletonIgnore

Wraps elements that should never receive a skeleton bone and always remain visible during loading: section headers, timestamps, decorative labels.

import { SkeletonIgnore } from 'react-zero-skeleton'

function PriceCard({ data }) {
  return (
    <View style={s.wrap}>
      <SkeletonIgnore>
        <Text style={s.label}>Live price</Text>
      </SkeletonIgnore>
      <Text style={s.value}>{data.price}</Text>
      <Text style={s.change}>{data.change}</Text>
    </View>
  )
}

The measurement layer skips SkeletonIgnore entirely. The text stays visible while the dynamic content animates around it.

---

SkeletonParagraph

A block of text measures as one tall rectangle, so its skeleton is a single solid pavé. Wrap it with SkeletonParagraph and it skeletons into several lines instead: body lines get a naturally ragged width and the last line is shortened, like real text.

import { SkeletonParagraph } from 'react-zero-skeleton'

function Article({ article }) {
  return (
    <View>
      <Text style={s.title}>{article.title}</Text>
      <SkeletonParagraph size="md">
        <Text style={s.body}>{article.body}</Text>
      </SkeletonParagraph>
    </View>
  )
}

Line count

size is a preset; lines overrides it with an exact count.

<SkeletonParagraph size="sm">…</SkeletonParagraph>   {/* 2 lines */}
<SkeletonParagraph size="md">…</SkeletonParagraph>   {/* 3 lines (default) */}
<SkeletonParagraph size="lg">…</SkeletonParagraph>   {/* 5 lines */}
<SkeletonParagraph lines={7}>…</SkeletonParagraph>  {/* exactly 7 */}

Alignment

The shortened last line follows the text alignment. Pass align explicitly, or leave it out and it is inherited from the wrapped component's textAlign (computed style on web, the wrapper's style on React Native).

{/* explicit */}
<SkeletonParagraph size="md" align="center">…</SkeletonParagraph>

{/* inherited: lines follow text-align: right */}
<div style={{ textAlign: 'right' }}>
  <SkeletonParagraph size="md"><p>{body}</p></SkeletonParagraph>
</div>

On React Native, textAlign lives on Text, not View. To inherit alignment, set textAlign on the SkeletonParagraph style, or pass the align prop (recommended for cross-platform).

Word mode

mode="words" breaks each line into word-sized bones separated by gaps, for a more text-like placeholder.

<SkeletonParagraph size="md" mode="words">
  <Text>{article.body}</Text>
</SkeletonParagraph>

Props

Prop	Type	Default	Description
size	'sm' | 'md' | 'lg'	'md'	Line count preset (2 / 3 / 5)
lines	number	—	Exact line count; overrides size
align	'left' | 'center' | 'right'	inherited → 'left'	Alignment of the lines
mode	'lines' | 'words'	'lines'	One bar per line, or word-sized bones
style	ViewStyle / CSSProperties	—	Style for the wrapper

All widths are deterministic, so they never flicker between renders. Works on web and React Native (iOS / Android).

---

Adaptive animation

Skelter detects nothing itself. You bring your own signal source (NetInfo, navigator.connection, expo-battery, Low Power Mode…) and feed the values. Skelter only maps them to an animation.

How it works

Pass conditions (your live signals) and an adaptive policy to SkeletonTheme or skeletonConfig. If a rule matches, its animation is used; if nothing matches, the animation prop you already set is used unchanged — the "everything is fine" case is free.

// React Native example (NetInfo + expo-battery)
import { useNetInfo } from '@react-native-community/netinfo';
import { useBatteryLevel, useLowPowerMode } from 'expo-battery';

function App() {
  const { type } = useNetInfo();
  const battery  = useBatteryLevel();   // 0..1
  const lowPower = useLowPowerMode();

  return (
    <SkeletonTheme
      animation="shatter"               // default: used when no rule matches
      conditions={{ network: type, battery, saveData: lowPower }}
      adaptive={[
        { when: { network: ['slow-2g', '2g'] }, use: 'none'  },
        { when: { saveData: true },             use: 'pulse' },
        { when: { batteryBelow: 0.2 },          use: 'pulse' },
        { when: { network: '3g' },              use: 'wave'  },
      ]}
    >
      <HomeScreen />
    </SkeletonTheme>
  );
}

// Web example (navigator.connection)
const conn = (navigator as any).connection;

<SkeletonTheme
  animation="wave"
  conditions={{
    network: conn?.effectiveType,
    saveData: conn?.saveData,
  }}
  adaptive={[
    { when: { network: ['slow-2g', '2g'] }, use: 'none'  },
    { when: { saveData: true },             use: 'pulse' },
  ]}
>

Rule matrix (declarative)

Rules are evaluated in order — the first match wins. Inside a rule, every key must hold (AND). Across rules, the first match is used (OR).

adaptive={[
  // AND: all conditions in a rule must hold
  { when: { network: '3g', saveData: true }, use: 'none' },

  // array = membership check
  { when: { network: ['slow-2g', '2g'] }, use: 'none' },

  // numeric threshold on battery (only matches when battery is known)
  { when: { batteryBelow: 0.2 }, use: 'pulse' },

  // custom signal — any key you put in conditions
  { when: { thermal: ['serious', 'critical'] }, use: 'none' },
]}

Function (escape hatch)

Return undefined to fall through to the base animation.

adaptive={(conditions) => {
  if (conditions.battery != null && conditions.battery < 0.15) return 'none';
  if (conditions.network === '3g' && conditions.saveData) return 'pulse';
  return undefined; // fall through → animation prop
}}

Per-element override

Like any SkeletonConfig, the per-element skeletonConfig takes priority over SkeletonTheme. Conditions deep-merge; the adaptive policy uses the most specific level.

// Global: wave on 3g
<SkeletonTheme animation="wave" conditions={...} adaptive={...}>

  // This card keeps its own policy regardless of the theme
  <HeavyCard
    hasSkeleton isLoading={loading}
    skeletonConfig={{
      animation: 'shatter',
      adaptive: [{ when: { batteryBelow: 0.3 }, use: 'pulse' }],
    }}
  />
</SkeletonTheme>

conditions fields

Field	Type	Description
network	NetworkType	'offline' | 'slow-2g' | '2g' | '3g' | '4g' | '5g' | 'wifi' | 'unknown'
battery	number	Battery level 0..1
charging	boolean	Whether the device is charging
saveData	boolean	OS data-saver / reduced-data preference
deviceTier	'low' | 'mid' | 'high'	Coarse device capability
reducedMotion	boolean	Accessibility reduce-motion (handled automatically if omitted)
[custom]	unknown	Any extra signal — matched by rule keys

---

API Reference

Props added by withSkeleton

Prop	Type	Description
hasSkeleton	boolean	Activates skeleton mode on this instance
isLoading	boolean	Shows the skeleton when true
isLoadingSkeleton	boolean	Shorthand: activates hasSkeleton + isLoading
skeletonConfig	SkeletonConfig	Per-instance config override

SkeletonConfig

Prop	Type	Default	Description
animation	'pulse' | 'wave' | 'shiver' | 'drip' | 'slide' | 'beat' | 'shaker' | 'shatter' | 'none'	'pulse'	Animation style
color	string	'#E0E0E0'	Base bone color
highlightColor	string	'#F5F5F5'	Highlight for wave / shiver / drip
speed	'slow' | 'normal' | 'rapid' | number	'normal'	Animation speed multiplier
borderRadius	number	4	Fallback corner radius
direction	'ltr' | 'rtl'	'ltr'	Shimmer direction
cascade	number	0	Stagger ms per pixel of vertical position
enter	'fade' | 'fadeUp' | 'fadeDown' | 'fadeLeft' | 'fadeRight' | 'none'	'none'	Skeleton enter animation
exit	'fade' | 'fadeUp' | 'fadeDown' | 'fadeLeft' | 'fadeRight' | 'none'	'fade'	Skeleton exit animation
revealOnExit	boolean	false	Show real content under skeleton during exit
minDuration	number	0	Minimum ms the skeleton stays visible
disabled	boolean	false	Disables skeleton entirely
shatterConfig	ShatterConfig	-	Shatter animation config
maxBonesInList	number	0	Max bones in FlatList (0 = unlimited)

withSkeleton(Component, options?)

Option	Type	Default	Description
measureStrategy	'auto' | 'root-only'	'auto'	auto = one bone per element; root-only = single block
maxDepth	number	8	Max Fiber tree depth
exclude	string[]	[]	Component displayNames to skip
mockProps	object	{}	Props for the invisible warmup render

mockProps: cold start

When real props carry no data on first load, mockProps provides a realistic layout for the warmup render:

withSkeleton(ArticleCard, {
  mockProps: { article: { title: 'Lorem ipsum', image: null } }
})

ShatterConfig

Prop	Type	Default	Description
cellSize	number	0 (auto)	Fixed cell size in px - overrides column count
stagger	number	80	ms delay between squares
fadeStyle	'random' | 'cascade' | 'radial'	'random'	Square fade order

registerSkeletonLeaf (React Native)

Registers custom image components as leaf elements in the Fiber walk:

import { registerSkeletonLeaf } from 'react-zero-skeleton'
registerSkeletonLeaf('FastImage', 'ExpoImage')

SkeletonTheme auto mode (React Native)

Injects hasSkeleton on all children via cloneElement. Then anywhere in the tree, only isLoading is needed:

<SkeletonTheme auto animation="wave" exclude={['MapView']}>
  <App />
</SkeletonTheme>

// Anywhere in the tree:
<ArticleCard isLoading={isLoading} />

---

FlatList

const items = isLoading ? Array(6).fill(null) : realData

<FlatList
  data={items}
  renderItem={({ item }) => (
    <ArticleCard
      article={item}
      hasSkeleton
      isLoading={item === null}
    />
  )}
/>

shatter falls back to pulse automatically inside FlatList / FlashList for performance. maxBonesInList caps the number of bones per cell when lists are long.

---

Accurate bones: fit-content

Block-level elements expand to fill their container by default, so their bone fills the full width even if the text is short. Add width: 'fit-content' (web) or alignSelf: 'flex-start' (React Native) to make each bone match the actual content width.

// Web
<p style={{ fontSize: 16, width: 'fit-content' }}>{title}</p>

// React Native
<Text style={{ fontSize: 16, alignSelf: 'flex-start' }}>{title}</Text>

---

Comparison

Feature	react-zero-skeleton	react-native-auto-skeleton	react-content-loader	react-loading-skeleton
Zero config	✅	✅	❌	❌
Auto-generated from live layout	✅	✅	❌	❌
React web support	✅	❌	✅	✅
Enter / exit transitions	✅	❌	❌	❌
Cascade stagger	✅	❌	❌	❌
Shatter animation	✅	❌	❌	❌
SkeletonBox / SkeletonIgnore	✅	❌	❌	❌
No native code	✅	❌	✅	✅
RTL support	✅	❌	❌	✅

---

Limitations

Fiber walk reads React internals: per-element measurement accesses _reactInternals / _reactFiber, which are undocumented but stable across React 17-18-19. If the walk fails, react-zero-skeleton falls back to a single root bone silently.

wave / shiver require a gradient peer on React Native: without expo-linear-gradient or react-native-linear-gradient, they fall back to a solid placeholder.

Animations run on the JS thread: all React Native animations use the Animated API. Reanimated worklets are on the roadmap for long lists on low-end devices.

---

Contributing

npm install
npm run build
npm test

Open a PR against main with a changeset:

npx changeset

---

License

MIT © J-Ben