@creuto/react-native-skeleton

Lightweight, Accessible & Zero-Dependency Skeleton Loading Library for React Native and TypeScript.

Overview

@creuto/react-native-skeleton is a high-performance, customizable, and accessible React Native skeleton loader library designed for mobile and web applications. Replace jarring spinner indicators and blank white screens with smooth 60 FPS shimmer wave or opacity pulse animations that match your UI design layout seamlessly.

Built with zero external runtime dependencies, @creuto/react-native-skeleton runs on React Native's native Animated engine—eliminating the need for complex native linking, Reanimated worklets, or third-party gradient libraries.

Table of Contents

• Features
• Why @creuto/react-native-skeleton?
• Installation
• Quick Start & Usage Examples
  • 1. Basic Skeleton Box
  • 2. Avatar Skeleton (<SkeletonCircle />)
  • 3. Paragraph Text Lines (<SkeletonText />)
  • 4. Card Layout (<SkeletonCard />)
  • 5. Loading State Transition (<SkeletonGroup />)
• Animation & Customization
• Dark Mode & Theme System
• Accessibility (a11y)
• API Reference
• Supported Platforms
• Performance Optimization
• Design Philosophy & Limitations
• Contributing
• License

Features

• Zero Runtime Dependencies — 100% pure React Native Animated solution with zero native setup.
• Multiple Animation Modes — Smooth 60 FPS shimmer wave, pulse fading, and static none placeholders.
• Automatic Dark Mode — Detects device theme (light/dark) with built-in color defaults out-of-the-box.
• Accessibility-First (a11y) — Automatically hides skeleton boxes from screen readers (VoiceOver / TalkBack).
• Ready-to-Use UI Patterns — Includes <Skeleton>, <SkeletonText>, <SkeletonCircle>, <SkeletonCard>, and <SkeletonGroup>.
• TypeScript Strict Mode — Fully typed interfaces and exports for autocompletion in VS Code.
• Ultra-Lightweight Footprint — Minimal JS bundle impact (~13 kB tarball) with zero native bloat.

Why @creuto/react-native-skeleton?

| Feature / Aspect | @creuto/react-native-skeleton | Other Skeleton Packages | | --- | --- | --- | | Dependencies | 0 runtime dependencies | Requires react-native-linear-gradient or react-native-reanimated | | Setup & Linking | Zero setup (Expo & Bare RN compatible) | Complex pod installs, native links, or Babel plugins | | Dark Mode | Built-in theme auto-detection | Manual color passing on every placeholder element | | Accessibility (a11y) | Screen reader hidden by default | Placeholders read as empty text boxes by screen readers | | Composition | Predictable <SkeletonGroup> switcher | Fragile automatic AST child parsing that breaks on custom components |

Installation

Install using your preferred package manager:

# npm
npm install @creuto/react-native-skeleton

# yarn
yarn add @creuto/react-native-skeleton

# pnpm
pnpm add @creuto/react-native-skeleton

Peer Dependencies: Requires react >= 17.0.0 and react-native >= 0.68.0.

Quick Start & Usage Examples

1. Basic Skeleton Box

import { Skeleton } from '@creuto/react-native-skeleton';

export function BannerPlaceholder() {
  return (
    <Skeleton
      width="100%"
      height={150}
      borderRadius={12}
      animation="shimmer"
    />
  );
}

2. Avatar Skeleton (<SkeletonCircle />)

import { SkeletonCircle } from '@creuto/react-native-skeleton';

export function AvatarPlaceholder() {
  return <SkeletonCircle size={56} animation="shimmer" />;
}

3. Paragraph Text Lines (<SkeletonText />)

import { SkeletonText } from '@creuto/react-native-skeleton';

export function TextPlaceholder() {
  return (
    <SkeletonText
      lines={3}
      lineHeight={16}
      spacing={8}
      lastLineWidth="60%"
    />
  );
}

4. Card Layout (<SkeletonCard />)

import { SkeletonCard } from '@creuto/react-native-skeleton';

export function FeedCardPlaceholder() {
  return (
    <SkeletonCard
      imageHeight={180}
      lines={3}
      spacing={12}
      borderRadius={8}
    />
  );
}

5. Loading State Transition (<SkeletonGroup />)

Easily toggle between skeleton loading states and actual content using <SkeletonGroup>:

import { SkeletonGroup, SkeletonCard } from '@creuto/react-native-skeleton';

export function UserProfileScreen({ isLoading, user }) {
  return (
    <SkeletonGroup
      loading={isLoading}
      fallback={<SkeletonCard imageHeight={200} lines={3} />}
    >
      <UserProfileCard name={user.name} avatar={user.avatarUrl} />
    </SkeletonGroup>
  );
}

Animation & Customization

Choose between three animation modes: shimmer, pulse, or none.

// 1. Shimmer animation (Default)
<Skeleton width="100%" height={24} animation="shimmer" duration={1200} />

// 2. Pulse animation
<Skeleton width="100%" height={24} animation="pulse" duration={1000} />

// 3. Static color placeholder (No animation)
<Skeleton width="100%" height={24} animation="none" />

// 4. Temporarily disable animation
<Skeleton width="100%" height={24} disabled={true} />

Dark Mode & Theme System

The library automatically checks the device color scheme via React Native's useColorScheme hook and applies appropriate theme defaults:

• Light Mode Defaults: Background #E1E9EE, Highlight #F2F8FC
• Dark Mode Defaults: Background #2A2E33, Highlight #3D444D

Custom Theme Colors

Override the default colors on any component:

<Skeleton
  width="100%"
  height={40}
  color="#E5E7EB"
  highlightColor="#F3F4F6"
/>

Accessibility (a11y)

@creuto/react-native-skeleton implements mobile accessibility best practices:

• Screen Reader Hiding: Skeleton boxes are tagged with accessibilityElementsHidden={true} and importantForAccessibility="no-hide-descendants". This prevents VoiceOver and TalkBack from reading meaningless placeholder boxes as real content.
• Loading State Indicator: <SkeletonGroup> sets accessibilityState={{ busy: true }} when loading={true} to notify assistive tech that data is fetching.

API Reference

<Skeleton />

Base skeleton placeholder element. Extends standard ViewProps.

| Prop | Type | Default | Description | | --- | --- | --- | --- | | width | DimensionValue | '100%' | Width of the skeleton container. | | height | DimensionValue | 20 | Height of the skeleton container. | | borderRadius | number | 4 | Border radius in pixels. | | animation | 'shimmer' \| 'pulse' \| 'none' | 'shimmer' | Animation mode. | | duration | number | 1200 | Loop animation cycle duration in ms. | | color | string | Theme Default | Custom base background color. | | highlightColor | string | Theme Default | Custom shimmer wave highlight color. | | disabled | boolean | false | Disables animation when set to true. | | style | StyleProp<ViewStyle> | undefined | Custom view container styles. |

<SkeletonText />

Renders multiple text line placeholders with a shorter last line.

| Prop | Type | Default | Description | | --- | --- | --- | --- | | lines | number | 3 | Number of text line placeholders. | | lineHeight | number | 16 | Height of each text line. | | spacing | number | 8 | Vertical spacing between lines. | | lastLineWidth | DimensionValue | '60%' | Width percentage or number for the last line. | | borderRadius | number | 4 | Border radius for line blocks. | | style | StyleProp<ViewStyle> | undefined | Container style for the text line group. |

<SkeletonCircle />

Circular skeleton placeholder helper (e.g. for user avatars).

| Prop | Type | Default | Description | | --- | --- | --- | --- | | size | number | 48 | Circle diameter in pixels (borderRadius defaults to size / 2). | | animation | 'shimmer' \| 'pulse' \| 'none' | 'shimmer' | Animation mode. | | color | string | Theme Default | Custom base background color. | | highlightColor | string | Theme Default | Custom highlight color. |

<SkeletonCard />

Compound layout skeleton containing an image placeholder and text lines.

| Prop | Type | Default | Description | | --- | --- | --- | --- | | imageHeight | number | 180 | Height of the top image skeleton block. | | lines | number | 3 | Number of text lines below the image. | | lineHeight | number | 16 | Height of each text line. | | spacing | number | 12 | Spacing between card elements. | | borderRadius | number | 8 | Border radius for the card components. |

<SkeletonGroup />

Container component for explicit loading-to-content state transitions.

| Prop | Type | Default | Description | | --- | --- | --- | --- | | loading | boolean | Required | Toggles between loading fallback and child content. | | children | ReactNode | Required | Real component content rendered when loading={false}. | | fallback | ReactNode | <SkeletonText /> | Custom skeleton component(s) shown when loading={true}. |

Supported Platforms

• iOS (React Native)
• Android (React Native)
• Expo (Managed & Bare Workflows)
• React Native Web

Performance Optimization

• Uses useNativeDriver: true for native thread execution at 60 FPS.
• Zero extra JavaScript bundle overhead — zero third-party graphics dependencies.

Design Philosophy & Limitations

• Predictable Composition: @creuto/react-native-skeleton avoids fragile runtime AST component parsing. Explicit layout composition with <SkeletonGroup> guarantees zero runtime bugs, complete type safety, and effortless code maintenance.

Contributing

Contributions are welcome! Please check out CONTRIBUTING.md to get started.

License

MIT © Creuto