instaskeleton

Ultra-light React skeleton loader with zero DOM scanning — the fastest way to add loading states to your React app

Live Demo 🚀

instaskeleton is the lightest React skeleton loading library that doesn't scan your DOM. Perfect for building fast, responsive loading states in React applications with shimmer animations, pulse effects, and automatic JSX inference.

~1.2 KB JS + ~0.45 KB CSS = ~1.65 KB gzipped (total)

Table of Contents

• Live Demo
• Features
• Installation
• Quick Start
• Manual Schema
• HOC Pattern
• API Reference
• Performance
• Browser Support
• License

Why instaskeleton?

The problem with other React skeleton loaders:

• They require separate skeleton components for every UI element (tedious)
• They scan the DOM at runtime to generate placeholders (slow, causes layout shifts)
• They bloat your bundle with unnecessary dependencies

instaskeleton solves this differently:

| Feature | Benefit | |---------|----------| | ⚡ Zero DOM scanning | No runtime layout measurement, no CLS issues | | 🚀 Zero work when not loading | Early exit skips all computation | | 🎯 Automatic JSX inference | Skeleton shapes generated from your React component tree | | 📐 Manual schema mode | Pixel-perfect control when you need exact layouts | | 💾 Smart LRU caching | Repeated renders are instant (100-entry limit) | | 🎨 Multiple animations | Shimmer, pulse, or none — GPU accelerated | | ♿ Accessibility first | Respects prefers-reduced-motion automatically | | 📦 Tiny bundle | Only ~1.65KB gzipped total |

Install

npm install instaskeleton

Import the bundled styles once:

import 'instaskeleton/styles.css';

Quick Start

Use inference when you want the fastest setup:

import { InstaSkeleton } from 'instaskeleton';
import 'instaskeleton/styles.css';

type Product = {
  title: string;
  price: string;
};

function ProductCard({
  loading,
  product
}: {
  loading: boolean;
  product: Product;
}) {
  return (
    <InstaSkeleton loading={loading} infer cacheKey="product-card-v1">
      <article>
        <img src="/cover.png" alt="" />
        <h3>{product.title}</h3>
        <p>{product.price}</p>
        <button>Add to cart</button>
      </article>
    </InstaSkeleton>
  );
}

Manual Schema

Use manual schema when you want the skeleton to resemble the inner component structure more closely.

import { InstaSkeleton, type SkeletonNode } from 'instaskeleton';

const articleCardSchema: SkeletonNode[] = [
  { type: 'rect', height: '12rem', radius: '1rem' },
  { type: 'line', width: '68%' },
  { type: 'line', width: '92%' },
  { type: 'line', width: '40%' }
];

function ArticleCard({ loading }: { loading: boolean }) {
  return (
    <InstaSkeleton loading={loading} schema={articleCardSchema} infer={false}>
      <article>
        <img src="/hero.png" alt="" />
        <h3>How we removed DOM scanning from loading states</h3>
        <p>Manual schema mirrors the actual card anatomy.</p>
        <small>5 min read</small>
      </article>
    </InstaSkeleton>
  );
}

HOC Pattern

Use withInstaSkeleton when you want to preconfigure loading behavior for a reusable component.

import { withInstaSkeleton } from 'instaskeleton';

function StatCard({ label, value }: { label: string; value: string }) {
  return (
    <div>
      <span>{label}</span>
      <strong>{value}</strong>
    </div>
  );
}

const StatCardWithSkeleton = withInstaSkeleton(StatCard, {
  skeleton: [
    { type: 'line', width: '35%', height: '0.75rem' },
    { type: 'rect', height: '3rem', radius: '0.75rem' }
  ],
  infer: false,
  cacheKey: 'stat-card'
});

<StatCardWithSkeleton loading={isLoading} label="Downloads" value="12.4k" />;

API Reference

<InstaSkeleton>

The main component for wrapping content with skeleton loading states.

| Prop | Type | Default | Description | |------|------|---------|-------------| | loading | boolean | required | Show skeleton when true, children when false | | children | ReactNode | required | Content to display when not loading | | schema | SkeletonNode \| SkeletonNode[] | undefined | Manual skeleton definition | | infer | boolean | true | Auto-generate skeleton from children | | cacheKey | string | undefined | Cache inferred schema for reuse | | className | string | undefined | Additional CSS class for the skeleton root | | animation | 'shimmer' \| 'pulse' \| 'none' | 'shimmer' | Animation style | | inferOptions | InferOptions | {} | Control inference behavior |

InferOptions

Fine-tune the inference algorithm:

| Option | Type | Default | Description | |--------|------|---------|-------------| | maxDepth | number | 6 | Maximum JSX tree depth to traverse | | maxNodes | number | 120 | Maximum nodes to process | | textLineHeight | string \| number | '0.95rem' | Height for text line skeletons |

withInstaSkeleton(Component, options)

HOC to create a skeleton-wrapped version of any component.

const WrappedComponent = withInstaSkeleton(MyComponent, {
  skeleton: [...],      // Manual schema
  infer: false,         // Disable inference
  cacheKey: 'my-comp',  // Cache key
  className: 'custom',  // Root class
  animation: 'pulse',   // Animation style
});

// Adds `loading` prop to the component
<WrappedComponent loading={isLoading} {...props} />

clearInstaSkeletonCache(key?)

Clear cached schemas:

import { clearInstaSkeletonCache } from 'instaskeleton';

// Clear specific cache entry
clearInstaSkeletonCache('product-card');

// Clear all cached schemas
clearInstaSkeletonCache();

SkeletonNode

Supported node types:

line — Text placeholder

{ type: 'line', width: '80%', height: '1rem' }

rect — Block placeholder (images, buttons, cards)

{ type: 'rect', width: '100%', height: '8rem', radius: '1rem' }

circle — Avatar or icon placeholder

{ type: 'circle', width: '3rem', height: '3rem' }

group — Container for nested nodes

{
  type: 'group',
  gap: '0.75rem',
  children: [
    { type: 'circle', width: '3rem', height: '3rem' },
    { type: 'line', width: '60%' },
    { type: 'line', width: '40%' },
  ]
}

Performance

Zero Work When Not Loading

// When loading=false, InstaSkeleton returns children immediately
// No inference, no schema processing, no DOM overhead
if (!loading) return <>{children}</>;

LRU Cache with Size Limit

Schemas are cached with a 100-entry limit to prevent memory leaks in long-running SPAs.

GPU-Accelerated Animations

Shimmer animation uses will-change: transform for 60fps performance.

Reduced Motion Support

Animations are disabled automatically when prefers-reduced-motion: reduce is set.

Choosing The Right Mode

| Use Case | Mode | Why | |----------|------|-----| | Quick prototyping | infer | Zero config, good approximation | | Production cards with specific layout | schema | Pixel-perfect control | | Reusable components | withInstaSkeleton | Consistent API, one config | | Lists with repeated items | infer + cacheKey | Cached after first render | | Complex nested structures | infer + inferOptions | Tune depth/node limits |

Development

npm run build        # Build the library
npm run typecheck    # Run TypeScript checks
npm run dev          # Watch mode

Browser Support

• Chrome/Edge 88+
• Firefox 78+
• Safari 14+

Keywords

react skeleton, skeleton loader, react loading, loading placeholder, shimmer animation, react placeholder, skeleton screen, loading state, react ui components, typescript skeleton, lightweight skeleton loader, zero dom scanning, jsx inference

License

MIT © LittleBoy9

Found this useful? Give it a ⭐ on GitHub!

Notes

• Inference walks the React element tree, not the rendered DOM.
• Function components may be unwrapped, but hook-heavy components can fall back to child inference.
• If you need strict visual matching, use manual schema.