react-native-render-queue

A performant render queue library for React Native that controls component rendering with configurable parallelism and beautiful shimmer placeholders.

Features

• Progressive Rendering - Control how many components render simultaneously
• Priority Queue - Assign priorities to ensure critical content renders first
• Shimmer Placeholders - Beautiful, animated loading placeholders out of the box
• Zero Dependencies - Uses only React Native's built-in Animated API
• TypeScript First - Full TypeScript support with comprehensive types
• Lightweight - Minimal bundle size impact

Why Use Render Queue?

When a React Native screen has many complex components, rendering them all at once can cause:

• Janky animations and transitions
• Slow initial render times
• Poor user experience on lower-end devices

react-native-render-queue solves this by:

1. Queuing components to render progressively
2. Limiting parallel renders to prevent frame drops
3. Showing beautiful placeholders while content loads
4. Allowing priority-based rendering for critical content

Installation

npm install react-native-render-queue
# or
yarn add react-native-render-queue

Quick Start

1. Wrap your app with the Provider

import { RenderQueueProvider } from 'react-native-render-queue';

function App() {
  return (
    <RenderQueueProvider config={{ maxParallelRenders: 2 }}>
      <MyScreen />
    </RenderQueueProvider>
  );
}

2. Wrap components with RenderQueueItem

import { RenderQueueItem, Shimmer } from 'react-native-render-queue';

function MyScreen() {
  return (
    <ScrollView>
      {/* Critical content - renders immediately */}
      <RenderQueueItem immediate>
        <Header />
      </RenderQueueItem>

      {/* These render progressively */}
      <RenderQueueItem placeholder={<Shimmer height={200} />}>
        <HeroImage />
      </RenderQueueItem>

      <RenderQueueItem priority={1} placeholder={<Shimmer height={100} />}>
        <FeaturedProducts />
      </RenderQueueItem>

      <RenderQueueItem priority={2} placeholder={<Shimmer height={300} />}>
        <RecommendationList />
      </RenderQueueItem>
    </ScrollView>
  );
}

API Reference

RenderQueueProvider

The context provider that manages the render queue.

<RenderQueueProvider config={config}>
  {children}
</RenderQueueProvider>

Config Options

| Property | Type | Default | Description | |----------|------|---------|-------------| | maxParallelRenders | number | 2 | Maximum components rendering simultaneously | | staggerDelay | number | 16 | Delay (ms) between starting each render | | defaultPlaceholder | ReactNode | null | Default placeholder for all queue items | | debug | boolean | false | Enable console logging for debugging |

RenderQueueItem

Wraps a component to be rendered through the queue.

<RenderQueueItem
  priority={0}
  placeholder={<Shimmer />}
  immediate={false}
  onRenderStart={() => console.log('Started')}
  onRenderComplete={() => console.log('Done')}
>
  <MyComponent />
</RenderQueueItem>

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | children | ReactNode | Required | Content to render | | priority | number | 0 | Lower = higher priority | | placeholder | ReactNode | Config default | Loading placeholder | | immediate | boolean | false | Skip queue, render immediately | | onRenderStart | () => void | - | Called when rendering begins | | onRenderComplete | () => void | - | Called when rendering completes | | style | ViewStyle | - | Container style | | id | string | Auto-generated | Unique identifier |

useQueuedRender Hook

For custom control over queued rendering:

import { useQueuedRender } from 'react-native-render-queue';

function CustomComponent() {
  const { isReady, markComplete, queuePosition } = useQueuedRender({
    priority: 1,
  });

  useEffect(() => {
    if (isReady) {
      // Perform expensive work
      loadData().then(() => markComplete());
    }
  }, [isReady]);

  if (!isReady) {
    return <Shimmer />;
  }

  return <ActualContent />;
}

Shimmer Components

Shimmer

Basic animated shimmer placeholder:

<Shimmer
  width={200}
  height={100}
  borderRadius={8}
  backgroundColor="#E0E0E0"
  highlightColor="#F5F5F5"
  duration={1000}
  animated={true}
/>

ShimmerGroup

Multiple shimmer placeholders:

<ShimmerGroup
  count={5}
  gap={12}
  direction="vertical"
  shimmerProps={{ height: 60, borderRadius: 8 }}
/>

ShimmerTemplates

Pre-built templates for common UI patterns:

import { ShimmerTemplates } from 'react-native-render-queue';

// Card placeholder
<ShimmerTemplates.Card />

// List item with avatar
<ShimmerTemplates.ListItem />

// Profile header
<ShimmerTemplates.ProfileHeader />

// Text paragraph
<ShimmerTemplates.Paragraph lines={4} />

Advanced Usage

Setting Default Placeholder

<RenderQueueProvider
  config={{
    maxParallelRenders: 3,
    defaultPlaceholder: <Shimmer height={100} />,
  }}
>
  {/* All RenderQueueItems will use this placeholder by default */}
</RenderQueueProvider>

Priority-Based Rendering

// Priority 0 (highest) - renders first
<RenderQueueItem priority={0}>
  <CriticalContent />
</RenderQueueItem>

// Priority 1 - renders after priority 0
<RenderQueueItem priority={1}>
  <ImportantContent />
</RenderQueueItem>

// Priority 2 - renders last
<RenderQueueItem priority={2}>
  <SecondaryContent />
</RenderQueueItem>

Monitoring Queue Status

import { useRenderQueue } from 'react-native-render-queue';

function QueueMonitor() {
  const { getQueueStatus, config } = useRenderQueue();

  const status = getQueueStatus();
  const queued = status.filter(item => item.status === 'queued').length;
  const rendering = status.filter(item => item.status === 'rendering').length;
  const rendered = status.filter(item => item.status === 'rendered').length;

  return (
    <Text>
      Queue: {queued} | Rendering: {rendering} | Done: {rendered}
    </Text>
  );
}

Without Provider (Graceful Degradation)

Components work without the provider - they just render immediately:

// This will render immediately since there's no provider
<RenderQueueItem placeholder={<Shimmer />}>
  <MyComponent />
</RenderQueueItem>

Performance Tips

1. Set appropriate maxParallelRenders

   • Lower values (1-2) for complex components
   • Higher values (3-4) for simpler components
   • Test on low-end devices

2. Use priorities wisely

   • Priority 0 for above-the-fold content
   • Higher priorities for below-the-fold content

3. Use immediate for critical content

   • Headers, navigation elements
   • Content users see first

4. Match placeholder dimensions

   • Prevents layout shifts when content loads

TypeScript

Full TypeScript support included:

import type {
  RenderQueueConfig,
  RenderQueueItemProps,
  ShimmerProps,
  ShimmerGroupProps,
} from 'react-native-render-queue';

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

Made with create-react-native-library