Skip to content
Projects

douglasjunior/react-native-gradient-shimmer

View on GitHub

douglasjunior/react-native-gradient-shimmer has 58 GitHub stars and 1 forks. GitHot measured -1 stars in 24 hours. Last checked 2026-11-16 03:38 UTC. Last push 2026-11-01.

How these counts are measured

Measured star growth

in 24h
-1
in 7 days
Update delayed
in 15 days
Update delayed
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

⚛ A pure JavaScript, performant, typed shimmer component for Android, iOS and Web

Web & Apps

README.md

Original

React Native Gradient Shimmer - Performant, fluid shimmer skeleton loader for React Native
A pure JavaScript, performant, typed shimmer component for Android, iOS, and Web.

React Native Gradient Shimmer delivers buttery smooth 60 FPS skeleton loading screens across Android, iOS, and Web. Powered by React Native's native Animated driver and flexible linear gradient engines (expo-linear-gradient or react-native-linear-gradient), it contains no native code in this package, supports declarative layout tree composition via ShimmerLayout, and coordinates animations across multiple skeleton elements.

MIT License npm version npm downloads Platform Android, iOS, and Web React Native >= 0.69.0 TypeScript strict PRs welcome

Quick Start · Why · Demo · Requirements · Installation · Usage · Shimmer Layout · API · Contributing


Quick Start

# 1. Install library
yarn add react-native-gradient-shimmer
# or: npm i -S react-native-gradient-shimmer

# 2. Install your preferred gradient provider (Expo or Bare RN)
npx expo install expo-linear-gradient
# or for bare React Native:
# yarn add react-native-linear-gradient && cd ios && pod install
import React from 'react';
import {SafeAreaView} from 'react-native';
import {LinearGradient} from 'expo-linear-gradient'; // or 'react-native-linear-gradient'
import GradientShimmer from 'react-native-gradient-shimmer';

export default function App() {
  return (
    <SafeAreaView style={{flex: 1, padding: 16}}>
      {/* Circle Avatar Skeleton */}
      <GradientShimmer
        LinearGradientComponent={LinearGradient}
        width={80}
        height={80}
        style={{borderRadius: 40, marginBottom: 16}}
      />

      {/* Text Line Skeleton */}
      <GradientShimmer
        LinearGradientComponent={LinearGradient}
        width={240}
        height={16}
        style={{borderRadius: 4, marginBottom: 8}}
      />
      <GradientShimmer
        LinearGradientComponent={LinearGradient}
        width={160}
        height={16}
        style={{borderRadius: 4}}
      />
    </SafeAreaView>
  );
}

Why Gradient Shimmer?

  • ⚡ Pure JavaScript Package. No native code inside this package—simply bring your preferred gradient engine (expo-linear-gradient in Expo or react-native-linear-gradient in bare React Native). Installs in seconds.
  • 🏎 60 FPS Animated Native Driver. Dispatches translation transforms directly to the native UI thread via useNativeDriver: true for smooth active animation playback.
  • 🌐 Cross-Platform Support. Delivers consistent behavior across Android, iOS, and Web (Expo Web or react-native-web).
  • 📐 Declarative ShimmerLayout Trees. Design intricate wireframes and multi-row skeleton loaders effortlessly using JSON layout configs with standard Flexbox properties (flexDirection, gap, justifyContent, alignItems).
  • 🔄 Synchronized Group Animations. Built-in AnimationProvider coordinates multiple skeleton elements into a shared Animated.parallel loop to keep related shimmer elements aligned together.
  • 🔌 Pluggable LinearGradient Engine. Decoupled gradient dependency: seamlessly plug in expo-linear-gradient in Expo apps or react-native-linear-gradient in bare React Native projects.
  • 🎨 Factory Customization. Generate reusable, pre-configured component instances using createGradientShimmer with your app's brand colors, duration, and custom easing curves.
  • 📦 Strict TypeScript Definitions. Comprehensive TypeScript typing for props, layout configurations, and container items out of the box.

Demo

Experience the live component in your browser or phone via the Snack Online Demo.

Android iOS Web
Android demo iOS demo Web demo

Requirements

Requirement Declared Peer Dep Effective Minimum Notes
react-native >= 0.60.0 >= 0.69.0 (or >= 0.71.0 for gap) Declared in peerDependencies. Note that GradientShimmer uses React 18+ (useId), and ShimmerLayout flexbox gap requires React Native 0.71+.
Linear Gradient Engine expo-linear-gradient or react-native-linear-gradient Latest stable Passed via the LinearGradientComponent prop.

Installation

1. Install Package

# Using Yarn
yarn add react-native-gradient-shimmer

# Using npm
npm i -S react-native-gradient-shimmer

2. Install Gradient Provider

Choose the gradient engine matching your workflow:

Option A: Expo (Managed or Bare)

npx expo install expo-linear-gradient

Option B: Bare React Native

yarn add react-native-linear-gradient
cd ios && pod install

Usage

Basic Direct Usage

Pass your preferred gradient component directly via the LinearGradientComponent prop:

import React from 'react';
import {View} from 'react-native';
import {LinearGradient} from 'expo-linear-gradient'; // or 'react-native-linear-gradient'
import GradientShimmer from 'react-native-gradient-shimmer';

export const UserCardSkeleton = () => {
  return (
    <View style={{flexDirection: 'row', alignItems: 'center', padding: 16}}>
      <GradientShimmer
        LinearGradientComponent={LinearGradient}
        width={56}
        height={56}
        style={{borderRadius: 28, marginRight: 12}}
      />
      <View style={{flex: 1}}>
        <GradientShimmer
          LinearGradientComponent={LinearGradient}
          width={140}
          height={14}
          style={{borderRadius: 4, marginBottom: 8}}
        />
        <GradientShimmer
          LinearGradientComponent={LinearGradient}
          width={90}
          height={12}
          style={{borderRadius: 4}}
        />
      </View>
    </View>
  );
};

Custom Shimmer Factory (createGradientShimmer)

Avoid repeating LinearGradientComponent and styling props on every skeleton item by creating a tailored shimmer instance with preset defaults:

import {Easing, View} from 'react-native';
import {LinearGradient} from 'expo-linear-gradient';
import {createGradientShimmer} from 'react-native-gradient-shimmer';

// Define reusable brand shimmer component
export const AppShimmer = createGradientShimmer({
  LinearGradientComponent: LinearGradient,
  backgroundColor: '#151838',
  highlightColor: '#2b3164',
  duration: 1200,
  easing: Easing.bezier(0.4, 0, 0.2, 1),
});

// Use anywhere without passing LinearGradientComponent again
export const ArticleSkeleton = () => (
  <View style={{padding: 16}}>
    <AppShimmer
      width={300}
      height={180}
      style={{borderRadius: 12, marginBottom: 12}}
    />
    <AppShimmer
      width={220}
      height={16}
      style={{borderRadius: 4, marginBottom: 8}}
    />
    <AppShimmer width={150} height={14} style={{borderRadius: 4}} />
  </View>
);

Synchronizing Multiple Elements (AnimationProvider)

When rendering multiple standalone GradientShimmer components on the same screen, wrap them in AnimationProvider to synchronize their highlight sweeps in parallel:

import React from 'react';
import {View} from 'react-native';
import {LinearGradient} from 'expo-linear-gradient';
import GradientShimmer, {
  AnimationProvider,
} from 'react-native-gradient-shimmer';

export const FeedSkeleton = () => {
  return (
    <AnimationProvider animating={true}>
      <View style={{gap: 16, padding: 16}}>
        <GradientShimmer
          LinearGradientComponent={LinearGradient}
          width={280}
          height={20}
        />
        <GradientShimmer
          LinearGradientComponent={LinearGradient}
          width={200}
          height={20}
        />
        <GradientShimmer
          LinearGradientComponent={LinearGradient}
          width={240}
          height={20}
        />
      </View>
    </AnimationProvider>
  );
};

For full working examples, explore the repository App.tsx.


Shimmer Layout

The ShimmerLayout component allows you to compose complex nested skeleton hierarchies declaratively using a JSON configuration tree. It automatically wraps items with AnimationProvider for synchronized animations.

import React from 'react';
import {SafeAreaView} from 'react-native';
import {LinearGradient} from 'expo-linear-gradient';
import {
  ShimmerLayout,
  ShimmerLayoutContainerType,
} from 'react-native-gradient-shimmer';

const postCardLayout: ShimmerLayoutContainerType = {
  style: {padding: 16, backgroundColor: '#0d0f27', borderRadius: 16},
  content: [
    // Header row: Avatar + User info
    {
      flexDirection: 'row',
      alignItems: 'center',
      marginBottom: 16,
      content: [
        {width: 48, height: 48, style: {borderRadius: 24}, marginRight: 12},
        {
          justifyContent: 'space-between',
          content: [
            {width: 140, height: 14, style: {borderRadius: 4}, marginBottom: 6},
            {width: 80, height: 12, style: {borderRadius: 4}},
          ],
        },
      ],
    },
    // Media Banner
    {width: 320, height: 180, style: {borderRadius: 12}, marginBottom: 14},
    // Text lines
    {width: 280, height: 14, style: {borderRadius: 4}, marginBottom: 8},
    {width: 210, height: 14, style: {borderRadius: 4}, marginBottom: 8},
    {width: 150, height: 12, style: {borderRadius: 4}},
  ],
};

export default function PostScreen() {
  return (
    <SafeAreaView
      style={{flex: 1, justifyContent: 'center', alignItems: 'center'}}>
      <ShimmerLayout
        LinearGradientComponent={LinearGradient}
        layout={postCardLayout}
        backgroundColor="#151838"
        highlightColor="#2c3268"
      />
    </SafeAreaView>
  );
}

API Reference

All components, types, and factories are exported from 'react-native-gradient-shimmer'.

GradientShimmer Props

Prop Type Default Description
LinearGradientComponent ComponentType<LinearGradientPropsType> Required Linear gradient component from expo-linear-gradient or react-native-linear-gradient.
width number Required Component width in DPI (must be a positive number).
height number Required Component height in DPI.
backgroundColor string 'rgb(200,200,200)' Base placeholder background color in HEX, RGB, or RGBA.
highlightColor string 'rgb(210,210,210)' Highlight shimmer beam color in HEX, RGB, or RGBA.
highlightWidth number 200 Width of the animated gradient highlight beam in DPI.
duration number 1500 Animation duration for a single pass in milliseconds.
animating boolean true Starts or stops the shimmer animation.
easing EasingFunction Easing.linear Easing function applied to Animated.timing().
style StyleProp<ViewStyle> undefined Styles passed to the container view (e.g. borderRadius, margin).
testID string undefined Identifier used for automated testing.

ShimmerLayout Props

Inherits properties from GradientShimmer except width, height, and style.

Prop Type Default Description
layout ShimmerLayoutContainerType Required Hierarchical layout configuration tree.
LinearGradientComponent ComponentType<LinearGradientPropsType> Required Linear gradient component from Expo or bare React Native.
defaultShimmerProps Omit<Partial<GradientShimmerPropsType>, 'LinearGradientComponent'> undefined Fallback props inherited by all layout items (colors, duration, etc.).
animating boolean true Controls animation playback for all nested items.

ShimmerLayoutContainerType

Defines a container node within the ShimmerLayout tree:

Property Type Description
content Array<ShimmerLayoutItemType | ShimmerLayoutContainerType> Array of nested container nodes or leaf shimmer items.
flexDirection 'row' | 'column' | 'row-reverse' | 'column-reverse' Flexbox layout direction.
alignItems FlexAlignType Alignment along the cross axis.
justifyContent 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly' Alignment along the main axis.
gap number Gutter spacing between rows and columns.
rowGap number Spacing between element rows.
columnGap number Spacing between element columns.
style StyleProp<ViewStyle> Custom styles applied to the container view.
marginTop / marginBottom / marginLeft / marginRight number Margin offsets for the container.

ShimmerLayoutItemType

Defines a leaf shimmer shape within the layout tree:

Property Type Description
width number Item width in DPI.
height number Item height in DPI.
style StyleProp<ViewStyle> Styles applied to the item (e.g., borderRadius).
marginTop / marginBottom / marginLeft / marginRight number Margin spacing for the item.

createGradientShimmer(fixedProps)

Creates a customized GradientShimmer component with preset props:

function createGradientShimmer<
  FixedProps extends Partial<GradientShimmerPropsType>,
>(fixedProps: FixedProps): FunctionComponent<NonFixedProps>;

AnimationProvider

Wraps multiple shimmer components to synchronize their loop cycles:

<AnimationProvider animating={true}>
  {/* Nested GradientShimmer components animate in parallel lockstep */}
</AnimationProvider>

Contributing

Contributions, bug reports, and suggestions are welcome!

  1. Fork the repository and create your feature branch: git checkout -b feat/my-feature.
  2. Verify code quality and typing:
    yarn lint
    yarn build
    
  3. Open a Pull Request detailing your changes.

For questions and feature requests, please open an issue.

Support the Maintainer

If this project saved you development time, consider supporting Douglas Junior:

Support on Patreon Donate with PayPal


Star History


License

The MIT License (MIT)

Copyright (c) 2023 Douglas Nassif Roma Junior

See the full license file.


Author & More Projects

Discover more open source projects by Douglas Junior

Discover more open-source libraries, creative animation engines, and developer tools at douglasjunior.work.