✨ @naresh-dhamu/react-native-skeleton

A lightweight, customizable, and performant skeleton loading library for React Native. Powered by React Native Reanimated and React Native Linear Gradient for silky-smooth, hardware-accelerated shimmer animations.

📸 Preview

🚀 Features

| Feature | Description | | :---------------------- | :----------------------------------------------------------------------------------- | | ⚡ Performant | Animations run on the native thread via Reanimated — zero jank. | | 🎨 Customizable | Full control over colors, speed, border radius & shimmer direction. | | 📐 Flexible Layouts | Use Skeleton.Item for manual layouts or auto-transform plain <View> hierarchies. | | 🔄 Shimmer Effects | Horizontal or diagonal (rotated) shimmer sweeps out-of-the-box. | | 🔧 Easy Toggle | Switch between skeleton and real content with a single enabled prop. | | 🟦 TypeScript | Fully typed with complete TypeScript support. |

📦 Installation

# Using yarn
yarn add @naresh-dhamu/react-native-skeleton

# Using npm
npm install @naresh-dhamu/react-native-skeleton

Peer Dependencies

Install the required peer dependencies:

# Using yarn
yarn add react-native-linear-gradient react-native-reanimated react-native-worklets

# Using npm
npm install react-native-linear-gradient react-native-reanimated react-native-worklets

[!NOTE] Make sure to follow the official configuration steps for React Native Reanimated (including adding the Babel plugin to your babel.config.js).

🛠️ Usage

[!TIP] See example/src/App.tsx for complete working demos — chips, posters, banners, and card layouts.

1. Manual Layout with Skeleton.Item

Build custom skeleton shapes using Skeleton.Item, which accepts any standard React Native ViewStyle props directly.

import React from 'react';
import { StyleSheet, View } from 'react-native';
import { Skeleton } from '@naresh-dhamu/react-native-skeleton';

export default function LoadingPlaceholder() {
  return (
    <Skeleton
      enabled={true}
      backgroundColor="#2A2A2A"
      highlightColor="#3A3A3A"
      borderRadius={8}
      rotated={true}
    >
      <View style={styles.container}>
        <Skeleton.Item
          width={60}
          height={60}
          borderRadius={30}
          marginRight={16}
        />
        <View style={styles.textContainer}>
          <Skeleton.Item width="80%" height={16} marginBottom={8} />
          <Skeleton.Item width="50%" height={12} />
        </View>
      </View>
    </Skeleton>
  );
}

const styles = StyleSheet.create({
  container: { flexDirection: 'row', alignItems: 'center', padding: 16 },
  textContainer: { flex: 1 },
});

2. Auto-Transform (Wrap Plain Views)

Wrap any existing <View> tree with <Skeleton> — no need for Skeleton.Item. The library automatically maps children to shimmering placeholders.

import React from 'react';
import { View } from 'react-native';
import { Skeleton } from '@naresh-dhamu/react-native-skeleton';

export default function AutoSkeleton() {
  return (
    <Skeleton enabled={true} backgroundColor="#2A2A2A" highlightColor="#3A3A3A">
      <View style={{ flexDirection: 'row', padding: 16 }}>
        <View style={{ width: 50, height: 50, borderRadius: 25 }} />
        <View style={{ marginLeft: 12, flex: 1, justifyContent: 'center' }}>
          <View style={{ width: '70%', height: 14, marginBottom: 6 }} />
          <View style={{ width: '40%', height: 10 }} />
        </View>
      </View>
    </Skeleton>
  );
}

3. Toggle Between Skeleton and Real Content

import React, { useState, useEffect } from 'react';
import { View, Text } from 'react-native';
import { Skeleton } from '@naresh-dhamu/react-native-skeleton';

export default function ProfileCard() {
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    setTimeout(() => setLoading(false), 2000);
  }, []);

  return (
    <Skeleton
      enabled={loading}
      backgroundColor="#1E1E1E"
      highlightColor="#2E2E2E"
    >
      <View style={{ flexDirection: 'row', padding: 16 }}>
        <View style={{ width: 56, height: 56, borderRadius: 28 }} />
        <View style={{ marginLeft: 12, flex: 1, justifyContent: 'center' }}>
          <Text style={{ fontSize: 16, fontWeight: 'bold', color: '#fff' }}>
            Naresh Dhamu
          </Text>
          <Text style={{ fontSize: 13, color: '#aaa', marginTop: 4 }}>
            @naresh-dhamu
          </Text>
        </View>
      </View>
    </Skeleton>
  );
}

📖 API Reference

<Skeleton> Props

| Prop | Type | Default | Description | | :-------------------- | :---------- | :---------- | :--------------------------------------------------------------------------- | | enabled | boolean | true | Show skeleton placeholders when true, render actual children when false. | | backgroundColor | string | "#2A2A2A" | Base color of the static placeholder shapes. | | highlightColor | string | "#3D3D3D" | Color of the animated shimmer gradient sweep. | | borderRadius | number | 4 | Default border radius applied to all child placeholder items. | | speed | number | 1200 | Duration (in milliseconds) of a single shimmer cycle. | | rotated | boolean | false | When true, shimmer sweeps diagonally instead of horizontally. | | containerStyle | ViewStyle | undefined | Optional style override for the skeleton's outer wrapper. |

<Skeleton.Item> Props

Accepts all standard React Native ViewStyle layout and flexbox props (e.g., width, height, margin, padding, flexDirection) directly, plus:

| Prop | Type | Default | Description | | :------------- | :---------------- | :---------- | :------------------------------------------------------------ | | rotated | boolean | Inherited | Override the global shimmer direction for this specific item. | | children | React.ReactNode | undefined | Nested React children inside this placeholder item. |

🤝 Contributing

Contributions are welcome! Please read the Contributing Guide and Code of Conduct before submitting a pull request.

👨‍💻 Author

📄 License

This project is licensed under the MIT License.

Copyright © 2026 Naresh Dhamu

See the LICENSE file for full details.