The Loading Pattern
Don't make users stare at a blank screen. Use
loading.py to
create an instant loading state while the destination route resolves.
1. User Click
Immediate
loading.py renders
2. Instant Feedback
0ms Delay3. Python Resolves
Async Data FetchHow it works
When a user navigates to a new route, Caspian immediately searches for a
loading.py in that
directory.
-
1The loading file is rendered instantly, preserving the layout.
-
2In parallel, the server runs
index.pyto fetch data. -
3Once resolved, the loading UI is swapped for the real page content.
The Structure
src/app/loading.py
Use the
pp-loading-content="true"
attribute to designate the element that represents the loading activity
(like a progress bar or skeleton).
loading.py markup
<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.