The Loading Pattern

Don't make users stare at a blank screen. Use loading.html to create instant loading states that execute before your Python logic resolves.

1. User Click

Immediate

loading.html renders

2. Instant Feedback

0ms Delay

3. Python Resolves

Async Data Fetch

How it works

When a user navigates to a new route, Caspian immediately searches for a loading.html in that directory.

1
The loading file is rendered instantly, preserving the layout.
2
In parallel, the server runs index.py to fetch data.
3
Once resolved, the loading UI is swapped for the real page content.

The Structure

src/app/loading.html

Use the pp-loading-content="true" attribute to designate the element that represents the loading activity (like a progress bar or skeleton).

HTML Template

<main class="overflow-y-auto bg-background p-8 lg:p-12 scroll-smooth">
  
  <!-- 
    The Loading Indicator 
    pp-loading-content="true" marks this as the active loader
  -->
  <div 
    pp-loading-content="true" 
    class="h-4 mx-auto max-w-4xl mb-4 rounded-full bg-teal-500/20 animate-pulse"
  ></div>
  
  <!-- 
    Children Injection 
    This is where the page content will eventually appear
  -->
  {{ children | safe }}

</main>

Pro Tip: Skeleton Screens

Instead of a simple spinner, try to mimic the layout of your actual page using gray boxes (skeletons). This reduces the cognitive load when the content finally snaps into place.