dead-lock-skeleton ⚙️

A lightweight, zero-dependency React library to instantly convert any React component tree into a beautiful, fluid shimmer skeleton loader with a single import wrapper.

Unlike traditional skeleton libraries, dead-lock-skeleton uses CSS layout-locking to prevent jarring content shifts, preserving your design's exact line heights, dimensions, and typography.

Key Features

• ⚡ Zero Setup: Wrap your existing components; no need to create separate, duplicate skeleton mockups.
• 🎯 No Layout Shift: Retains the exact dimensions, text alignment, and spacing of your active UI.
• 🎨 Fully Customizable: Adjust skeleton colors, shimmer speed, and corner rounding via React props or CSS custom properties.
• 🌗 Dark Mode Ready: Seamlessly responds to dark themes out of the box.
• 🚀 Performance First: Powered by hardware-accelerated CSS keyframe animations—zero Javascript overhead at render time.
• 🛠️ Opt-In/Opt-Out Control: Easily exclude specific buttons, icons, or badges from being skeletonized using helper classes.

Installation

npm install dead-lock-skeleton

Import Styles

Import the required CSS once at the entry point of your React application (usually main.tsx, index.tsx, or _app.tsx):

import 'dead-lock-skeleton/dist/style.css';

Quick Start (Usecase in React)

Wrap your component with <DeadLockSkeleton> (or alias <AutoSkeleton>) and control the skeleton screen using the loading prop:

import React, { useState, useEffect } from 'react';
import { DeadLockSkeleton } from 'dead-lock-skeleton';

function UserProfileCard() {
  const [loading, setLoading] = useState(true);
  const [user, setUser] = useState<any>(null);

  useEffect(() => {
    fetch('/api/user')
      .then((res) => res.json())
      .then((data) => {
        setUser(data);
        setLoading(false);
      });
  }, []);

  return (
    <DeadLockSkeleton loading={loading} theme="dark">
      <div className="profile-card">
        {/* Adds circle shape helper */}
        <img 
          src={user?.avatar} 
          className="avatar skeleton-circle" 
          alt={user?.name} 
        />
        <h3>{user?.name}</h3>
        <p>{user?.bio}</p>
        
        {/* Dynamic elements you don't want to turn into skeletons */}
        <span className="badge skeleton-exclude">
          🔥 Featured
        </span>
        
        <button className="btn">Send Invite</button>
      </div>
    </DeadLockSkeleton>
  );
}

API Reference

1. DeadLockSkeleton (alias AutoSkeleton)

| Prop | Type | Default | Description | | :--- | :--- | :--- | :--- | | loading | boolean | Required | When true, automatically overlays all typography, media, and input elements with shimmer loaders. | | theme | 'light' \| 'dark' | System | Forces a specific theme. By default, it detects user preferences (prefers-color-scheme). | | skeletonColor | string | #e2e8f0 | Overrides the base skeleton background color. | | shimmerColor | string | #f1f5f9 | Overrides the linear gradient shimmer wave highlight color. | | duration | string | 1.5s | Overrides the animation duration (e.g. 0.8s, 2s). | | borderRadius | string | 6px | Overrides the default skeleton box border-radius. | | as | React.ElementType | 'div' | The wrapping DOM element (e.g., 'div', 'section', 'article'). |

2. Standalone Skeleton

For custom mockups or fully customized loading layouts outside the auto-wrapper.

| Prop | Type | Default | Description | | :--- | :--- | :--- | :--- | | width | string \| number | 100% | Width of the placeholder (e.g., 120, "80px", "100%"). | | height | string \| number | 16px | Height of the placeholder. | | circle | boolean | false | Convenience toggle to force a circular shape (border-radius: 50%). | | borderRadius | string \| number | 6px | Specific border-radius for this component. |

Selective Styling & Tuning

To ensure your layout-locked skeleton looks outstanding, the library supports simple utility tokens:

Exclusions (skeleton-exclude / [data-skeleton-exclude])

Sometimes, components like dynamic badges, status indicators, or loaded static elements should remain visible instead of skeletonizing. Simply attach the class or data attribute:

<span className="status-badge skeleton-exclude">ONLINE</span>

Circle Shapes (skeleton-circle / [data-skeleton-shape="circle"])

Ensures avatars and circular icons receive a circular mask instead of rounded rectangular corners:

<img src={avatar} className="skeleton-circle" />

CSS Variables Theme Configuration

You can also control skeleton loaders globally using CSS variables within your stylesheet:

:root {
  --skeleton-bg: #cbd5e1;
  --skeleton-shimmer: #f8fafc;
  --skeleton-duration: 1.2s;
  --skeleton-radius: 12px;
}