Loading States

Show a placeholder while your component loads by creating a .loading.html file.

How It Works

1. Create a file named {component}.loading.html next to your component
2. The Vite plugin automatically injects it before your component element
3. When the component loads, the loading state is removed

Simple Loading State

<!-- modal.loading.html -->
<div aria-busy="true">Loading...</div>

Pico CSS styles aria-busy="true" with a spinner automatically.

Skeleton Loading

For a more polished experience, create skeleton placeholders that match your component's layout:

<!-- card.loading.html -->
<article class="skeleton">
    <div class="skeleton-image"></div>
    <div class="skeleton-line"></div>
    <div class="skeleton-line short"></div>
</article>

Demo

Technical Details

The loading HTML is injected as a sibling element with a data-loading-for attribute:

<!-- What the browser sees before component loads -->
<div data-loading-for="modal">
    <div aria-busy="true">Loading...</div>
</div>
<div x-component="modal"></div>

<!-- After component loads, the loading wrapper is removed -->

When to Use Loading States

• Event-triggered components — Show feedback immediately when user clicks
• Slow network conditions — Prevent layout shift as components load
• Complex components — Large components with significant JS may take time to initialize

Styling Tips

• Match the loading state dimensions to the final component to prevent layout shift
• Use CSS animations for skeleton shimmer effects
• Keep loading states simple — they should load instantly