✨ Shimmer From Structure

A React, Vue & Svelte shimmer/skeleton library that automatically adapts to your component's runtime structure. Unlike traditional shimmer libraries that require pre-defined skeleton structures, this library analyzes your actual component's DOM at runtime and generates a shimmer effect that perfectly matches its layout.

!React
!Vue
!Svelte

!Shimmer From Structure Demo

Why This Library?

Traditional shimmer libraries require you to:

- Manually create skeleton components that mirror your real components
- Maintain two versions of each component (real + skeleton)
- Update skeletons every time your layout changes

Shimmer From Structure eliminates all of that:

- ✅ Works with React, Vue & Svelte - Simple, framework-specific drivers
- ✅ Automatically measures your component's structure at runtime
- ✅ Generates shimmer effects that match actual dimensions
- ✅ Zero maintenance - works with any layout changes
- ✅ Works with complex nested structures
- ✅ Supports dynamic data with templateProps
- ✅ Preserves container backgrounds during loading
- ✅ Auto-detects border-radius from your CSS

Installation

``bash
npm install shimmer-from-structure


or

yarn add shimmer-from-structure

or

pnpm add shimmer-from-structure
`

🎯 Framework Support

Shimmer From Structure provides dedicated packages for React and Vue.

$3

React support is built-in to the main package for backward compatibility:

`javascript
// React projects (or @shimmer-from-structure/react)
import { Shimmer } from 'shimmer-from-structure';
`

$3

Vue support requires importing from the specific adapter:

`javascript
// Vue 3 projects
import { Shimmer } from '@shimmer-from-structure/vue';
`

$3

Svelte support is provided via its own adapter:

`javascript
// Svelte projects
import { Shimmer } from '@shimmer-from-structure/svelte';
`

---

📖 Basic Usage

React

$3

For components with hardcoded/static content:

`tsx
import { Shimmer } from 'shimmer-from-structure';

function UserCard() {
return (





);
}
`

Vue

$3

`vue



`

Svelte

$3

`svelte







`

---

$3

For components that receive dynamic data via props, use templateProps to provide mock data for skeleton generation:

React

`tsx
import { Shimmer } from 'shimmer-from-structure';

// Your component that accepts props
const UserCard = ({ user }) => (


);

// Template data for the skeleton
const userTemplate = {
name: 'Loading...',
role: 'Loading role...',
avatar: 'placeholder.jpg',
};

function App() {
const [loading, setLoading] = useState(true);
const [user, setUser] = useState(null);

return (



);
}
`

Vue

`vue



`

Svelte

`svelte





`

The templateProps object is spread onto the first child component when loading, allowing it to render with mock data for measurement.

🎨 API Reference

$3

| Prop | Type | Default | Description |
| ---------------------- | ------------------------- | -------------------------- | --------------------------------------------------------- |
| loading | boolean | true | Whether to show shimmer effect or actual content |
| children | React.ReactNode | required | The content to render/measure |
| shimmerColor | string | 'rgba(255,255,255,0.15)' | Color of the shimmer wave |
| backgroundColor | string | 'rgba(255,255,255,0.08)' | Background color of shimmer blocks |
| duration | number | 1.5 | Animation duration in seconds |
| fallbackBorderRadius | number | 4 | Border radius (px) for elements with no CSS border-radius |
| templateProps | Record | - | Props to inject into first child for skeleton rendering |

$3

React

`tsx
loading={isLoading}
shimmerColor="rgba(255, 255, 255, 0.2)"
backgroundColor="rgba(255, 255, 255, 0.1)"
duration={2}
fallbackBorderRadius={8}
templateProps={{
user: userTemplate,
settings: settingsTemplate,
}}
>


`

Vue

`vue
:loading="isLoading"
shimmerColor="rgba(255, 255, 255, 0.2)"
backgroundColor="rgba(255, 255, 255, 0.1)"
:duration="2"
:fallbackBorderRadius="8"
:templateProps="{
user: userTemplate,
settings: settingsTemplate,
}"
>


`

Svelte

`svelte
loading={isLoading}
shimmerColor="rgba(255, 255, 255, 0.2)"
backgroundColor="rgba(255, 255, 255, 0.1)"
duration={2}
fallbackBorderRadius={8}
templateProps={{
user: userTemplate,
settings: settingsTemplate,
}}
>


`

🔧 How It Works

1. Visible Container Rendering: When loading={true}, your component renders with transparent text but visible container backgrounds
2. Template Props Injection: If templateProps is provided, it's spread onto the first child so dynamic components can render
3. DOM Measurement: Uses useLayoutEffect to synchronously measure all leaf elements via getBoundingClientRect()
4. Border Radius Detection: Automatically captures each element's computed border-radius from CSS
5. Shimmer Generation: Creates absolutely-positioned shimmer blocks matching measured dimensions
6. Animation: Applies smooth gradient animation that sweeps across each block

$3

- Container backgrounds visible: Unlike opacity: 0, we use color: transparent so card backgrounds/borders show during loading
- Auto border-radius: Circular avatars get circular shimmer blocks automatically
- Fallback radius: Text elements (which have border-radius: 0) use fallbackBorderRadius to avoid sharp rectangles
- Dark-mode friendly: Default colors use semi-transparent whites that work on any background

Examples

$3

Each section can have its own independent loading state:

React

`tsx
function Dashboard() {
const [loadingUser, setLoadingUser] = useState(true);
const [loadingStats, setLoadingStats] = useState(true);

return (
<>
{/ User profile section /}




{/ Stats section - with custom colors /}
loading={loadingStats}
templateProps={{ stats: statsTemplate }}
shimmerColor="rgba(20, 184, 166, 0.2)"
>



);
}
`

Vue

`vue

`

Svelte

`svelte




loading={loadingStats}
templateProps={{ stats: statsTemplate }}
shimmerColor="rgba(20, 184, 166, 0.2)"
>


`

$3

React

`tsx



`

Vue

`vue



`

Svelte

`svelte



`

$3

React

`tsx



`

Vue

`vue



`

Svelte

`svelte



`

🔄 Using with React Suspense

Shimmer works seamlessly as a Suspense fallback. When used this way, loading is always true because React automatically unmounts the fallback and replaces it with the resolved component.

$3

`tsx
import { Suspense, lazy } from 'react';
import { Shimmer } from 'shimmer-from-structure';

const UserProfile = lazy(() => import('./UserProfile'));

function App() {
return (
fallback={



}
>


);
}
`

$3

When using Shimmer as a Suspense fallback:

1. Suspend: React renders the fallback → Shimmer shows with loading={true}
2. Resolve: React replaces the entire fallback with the real component
3. The Shimmer is unmounted, not updated — so you never need to toggle loading

$3

Memoize the fallback to prevent re-renders:

`tsx
const ShimmerFallback = React.memo(() => (



));

// Usage
}>

;
`

Keep templates lightweight — the DOM is measured synchronously via useLayoutEffect, so avoid complex logic in your template.

Global Configuration

You can set default configuration for your entire app (or specific sections) using the context/provider pattern. This is perfect for maintaining consistent themes without repeating props.

$3

`tsx
import { Shimmer, ShimmerProvider } from '@shimmer-from-structure/react';

function App() {
return (
// Set global defaults
config={{
shimmerColor: 'rgba(56, 189, 248, 0.4)', // Blue shimmer
backgroundColor: 'rgba(56, 189, 248, 0.1)', // Blue background
duration: 2.5,
fallbackBorderRadius: 8,
}}
>


);
}
`

$3

`vue




`

$3

`svelte




`

---

Components inside the provider automatically inherit values. You can still override them locally:

React

`tsx
// Inherits blue theme from provider


// Overrides provider settings

`

Vue

`vue





`

Svelte

`svelte





`

$3

If you need to access the current configuration in your own components:

React

`tsx
import { useShimmerConfig } from 'shimmer-from-structure';

function MyComponent() {
const config = useShimmerConfig();
return

;
}
`

Vue

`javascript
import { useShimmerConfig } from '@shimmer-from-structure/vue';

const config = useShimmerConfig();
console.log(config.value.backgroundColor);
`

Svelte

`javascript
import { getShimmerConfig } from '@shimmer-from-structure/svelte';

const config = getShimmerConfig();
console.log(config.backgroundColor);
`

Best Practices

$3

When your component receives data via props, always provide templateProps with mock data that matches the expected structure.

$3

Ensure your template data has the same array length and property structure as real data for accurate shimmer layout.

$3

Wrap each section in its own Shimmer for independent loading states:

`tsx
// ✅ Good - independent loading



// ❌ Avoid - all-or-nothing loading




`

$3

Block elements like

,

take full container width. If you want shimmer to match text width:

`css
.title {
width: fit-content;
}
`

$3

For async components (like charts), ensure containers have explicit dimensions so shimmer has something to measure.

⚡ Performance Considerations

- Measurement happens only when loading changes to true
- Uses useLayoutEffect for synchronous measurement (no flicker)
- Minimal re-renders - only updates when loading state or children change
- Lightweight DOM measurements using native browser APIs

- Lightweight DOM measurements using native browser APIs

🛠️ Development

This is a monorepo managed with npm workspaces. Each package can be built independently:

`bash


Install dependencies

npm install

Build all packages

npm run build

Build individual packages

npm run build:core
npm run build:react
npm run build:vue
npm run build:svelte
npm run build:main

Run tests

npm test
`

📝 License

MIT

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🐛 Known Limitations

- Async components: Components that render asynchronously (like charts using ResponsiveContainer) may need explicit container dimensions
- Zero-dimension elements: Elements with display: none or zero dimensions won't be captured
- SVG internals: Only the outer element is captured, not internal paths/shapes

🏗️ Monorepo Structure

This library is organized as a monorepo with four packages:

| Package | Description | Size |
| -------------------------------- | ------------------------------------------- | -------- |
| @shimmer-from-structure/core | Framework-agnostic DOM utilities | 1.44 kB |
| @shimmer-from-structure/react | React adapter | 12.84 kB |
| @shimmer-from-structure/vue | Vue 3 adapter | 3.89 kB |
| @shimmer-from-structure/svelte | Svelte adapter | 4.60 kB |
| shimmer-from-structure | Main package (React backward compatibility) | 0.93 kB |

The core package contains all DOM measurement logic, while React and Vue packages are thin wrappers that provide framework-specific APIs.

🚧 Roadmap

- [x] Dynamic data support via templateProps`
- [x] Auto border-radius detection
- [x] Container background visibility
- [x] Vue.js adapter
- [x] Svelte adapter
- [ ] Better async component support
- [ ] Customizable shimmer direction (vertical, diagonal)
- [ ] React Native support

---

Made with ❤️ for developers tired of maintaining skeleton screens