Skeleton Auto

Overview

Skeleton Auto provides framework-specific wrapper components that apply a CSS-only skeleton mask to their children. When isLoading is true, all descendant text, borders, and images are temporarily hidden behind an animated placeholder surface. No JavaScript drives the animation — the entire pulse effect is handled by a single CSS @keyframes rule.

Each package ships with zero runtime dependencies. The total footprint per package is approximately 2 KB gzipped.

Packages

| Package | Framework | Peer Dependency | | ---------------------------------------------------------------------------------------------- | ----------------------- | -------------------------------- | | @rimubhai/skeleton-auto-react | React 17+ / Next.js 13+ | react >= 17, react-dom >= 17 | | @rimubhai/skeleton-auto-vue | Vue 3.3+ / Nuxt 3 | vue >= 3.3 |

Installation

# React
npm install @rimubhai/skeleton-auto-react

# Vue
npm install @rimubhai/skeleton-auto-vue

Quick Start

React

import { AutoSkeleton } from "@rimubhai/skeleton-auto-react";

function Profile({ user, loading }) {
  return (
    <AutoSkeleton isLoading={loading}>
      <img src={user.avatar} alt="" />
      <h1>{user.name}</h1>
      <p>{user.bio}</p>
    </AutoSkeleton>
  );
}

The component includes the "use client" directive and is fully compatible with the Next.js App Router. During SSR, the stylesheet is registered inside a useEffect guard to avoid server-side DOM access.

Vue

<script setup lang="ts">
import { AutoSkeleton } from "@rimubhai/skeleton-auto-vue";
import { ref } from "vue";

const loading = ref(true);
</script>

<template>
  <AutoSkeleton :is-loading="loading">
    <h1>{{ user.name }}</h1>
    <p>{{ user.bio }}</p>
  </AutoSkeleton>
</template>

API

Props

| Prop | Type | Default | Description | | --------------------- | --------- | ------- | --------------------------------------------------------------------------------- | | isLoading | boolean | — | When true, the skeleton mask is active. When false, children render normally. | | className (React) | string | "" | Additional CSS class(es) appended to the skeleton wrapper. | | class (Vue) | string | "" | Additional CSS class(es) appended to the skeleton wrapper. |

Accessibility

The skeleton wrapper renders with aria-busy="true" so assistive technologies can detect the loading state.

Theming

Override the skeleton color by setting a single CSS custom property anywhere in your stylesheet:

:root {
  --auto-skeleton-color: #6366f1;
}

Dark mode detection is automatic. When the system preference is prefers-color-scheme: dark, the default fill color shifts from #e2e8f0 to #334155. Your --auto-skeleton-color override takes precedence in both modes.

@media (prefers-color-scheme: dark) {
  :root {
    --auto-skeleton-color: #1e293b;
  }
}

Architecture

When isLoading transitions to true, the component wraps its children in a <div> decorated with the auto-skeleton-active class. An injected stylesheet then applies the following ruleset to all descendants:

1. Text concealment — color: transparent on every descendant element.
2. Border removal — border-color: transparent and box-shadow: none.
3. Placeholder fill — targeted elements (h1–h3, span, button, a, li, img) receive a background-color backed by --skeleton-bg.
4. Image replacement — <img> tags are pushed off-canvas via object-position while retaining layout dimensions.
5. Multi-line paragraphs — empty <p> tags render three horizontal stripes using a linear-gradient background, simulating lines of text.
6. SVG suppression — inline SVG graphics are set to opacity: 0.

The opacity pulse animation runs on a 1.5-second cubic-bezier curve. No setInterval, no requestAnimationFrame, no forced synchronous layout.

Repository

This is an npm workspaces monorepo.

skeleton-auto/
├── packages/
│   ├── react/           # tsup  — CJS + ESM + declarations
│   └── vue/             # vite  — ESM + UMD + declarations
├── package.json         # Workspace root (private)
└── tsconfig.base.json   # Shared TypeScript configuration

Development

git clone <repo-url>
cd skeleton-auto
npm install

npm run build          # Build all packages
npm run build:react    # Build React only
npm run build:vue      # Build Vue only
npm run clean          # Remove dist directories

Publishing

npm run publish:all

Requires npm login and write access to the @rimubhai scope. The publishConfig.access field in each package is set to "public".

Contributing

1. Fork the repository.
2. Create a branch: git checkout -b feat/description.
3. Make changes and verify the build: npm run build.
4. Commit using Conventional Commits (feat:, fix:, docs:).
5. Open a pull request.

Both framework packages must maintain API parity. If a prop is added to one, it must be added to the other.

License

MIT