foxlau/react-router-better-auth / .agents/skills/react-router-framework-mode
react-router-framework-mode
VerifiedBuild full-stack React applications using React Router's framework mode. Use when configuring routes, working with loaders and actions, handling forms, handling navigation, pending/optimistic UI, error boundaries, or working with react-router.config.ts or other react router conventions.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.5 KB |
| references/actions.md | markdown | 8.9 KB |
| references/data-loading.md | markdown | 3.8 KB |
| references/error-handling.md | markdown | 4.5 KB |
| references/middleware.md | markdown | 6.6 KB |
| references/navigation.md | markdown | 4.1 KB |
| references/pending-ui.md | markdown | 6.8 KB |
| references/rendering-strategies.md | markdown | 3.8 KB |
| references/route-modules.md | markdown | 8.5 KB |
| references/routing.md | markdown | 6.0 KB |
| references/sessions.md | markdown | 10.2 KB |
| references/special-files.md | markdown | 12.2 KB |
| references/type-safety.md | markdown | 4.1 KB |
references/pending-ui.md
View on GitHub---
title: Pending UI and Optimistic Updates
description: Loading states, optimistic UI, useNavigation, and fetcher states
tags: [pending-ui, optimistic-ui, loading, useNavigation, useFetcher, spinner]
---
# Pending UI and Optimistic Updates
**Key principle:** Show expected results immediately using `fetcher.formData`, then let React Router sync with the server.
## Quick Reference
| Pattern | Hook | Use Case |
| ------------------------ | ------------------------- | -------------------------- |
| Optimistic mutations | `useFetcher` + `formData` | Likes, ratings, toggles |
| Global loading indicator | `useNavigation` | Page-level spinner |
| Link pending state | `NavLink` | Nav item loading indicator |
| Deferred data | `Await` + `Suspense` | Stream slow data |
For mutation patterns (when to use Form vs useFetcher), see [actions.md](./actions.md#choosing-the-right-pattern).
---
## useNavigation
Track global navigation state:
```tsx
import { useNavigation } from "react-router";
export default function Root() {
const navigation = useNavigation();
const isNavigating = Boolean(navigation.location);
return (
<html>
<body className={isNavigating ? "loading" : ""}>
{isNavigating && <GlobalSpinner />}
<Outlet />
</body>
</html>
);
}
```
### Navigation States
- `navigation.state` - `"idle"`, `"loading"`, or `"submitting"`
- `navigation.location` - The location being navigated to (if any)
- `navigation.formData` - Form data being submitted (if any)
- `navigation.formMethod` - HTTP method of the submission
```tsx
const navigation = useNavigation();
// Check if navigating
const isNavigating = navigation.state !== "idle";
// Check if submitting a form
const isSubmitting = navigation.state === "submitting";
// Check if loading after submission
const isLoading = navigation.state === "loading";
```
## NavLink Pending State
Show pending state on the specific link being clicked:
```tsx
import { NavLink } from "react-router";
function Nav() {
return (
<NavLink to="/dashboard">
{({ isPending }) => <span>Dashboard {isPending && <Spinner />}</span>}
</NavLink>
);
}
```
Or use className:
```tsx
<NavLink
to="/dashboard"
className={({ isPending }) => (isPending ? "pending" : "")}
>
Dashboard
</NavLink>
```
## useFetcher for Local State
Each fetcher tracks its own state independently:
```tsx
import { useFetcher } from "react-router";
function LikeButton({ postId, liked }) {
const fetcher = useFetcher();
// Show pending state while submitting
const isPending = fetcher.state !== "idle";
return (
<fetcher.Form method="post" action={`/posts/${postId}/like`}>
<button disabled={isPending}>
{isPending ? "..." : liked ? "Unlike" : "Like"}
</button>
</fetcher.Form>
);
}
```
### Fetcher States
- `fetcher.state` - `"idle"`, `"submitting"`, or `"loading"`
- `fetcher.data` - Data returned from the action/loader
- `fetcher.formData` - Form data being submitted
## Optimistic UI with useFetcher (Recommended Pattern)
**This is the standard pattern for mutations.** Show the expected result immediately using `fetcher.formData`:
```tsx
import { useFetcher } from "react-router";
function LikeButton({ postId, initialLiked }) {
const fetcher = useFetcher();
// Optimistic: check pending form data first, fallback to server state
const liked = fetcher.formData
? fetcher.formData.get("liked") === "true"
: initialLiked;
return (
<fetcher.Form method="post" action={`/posts/${postId}/like`}>
<input type="hidden" name="liked" value={String(!liked)} />
<button>{liked ? "❤️" : "🤍"}</button>
</fetcher.Form>
);
}
```
### Complete Optimistic UI Example
```tsx
import { useFetcher } from "react-router";
function RatingStars({ itemId, currentRating }) {
const fetcher = useFetcher();
// 1. Check if we're submitting - use the pending value
// 2. Otherwise use the server value
const displayRating = fetcher.formData
? Number(fetcher.formData.get("rating"))
: currentRating;
const isSubmitting = fetcher.state !== "idle";
return (
<fetcher.Form method="post" action={`/items/${itemId}/rate`}>
<div style={{ opacity: isSubmitting ? 0.5 : 1 }}>
{[1, 2, 3, 4, 5].map((star) => (
<button key={star} type="submit" name="rating" value={star}>
{star <= displayRating ? "★" : "☆"}
</button>
))}
</div>
</fetcher.Form>
);
}
```
### Why fetcher.formData?
- **Instant feedback** - UI updates immediately on click
- **No loading spinners needed** - the optimistic state IS the loading state
- **Automatic rollback** - if the action fails, loaders revalidate and reset to server state
## Optimistic UI with useNavigation
For form submissions that navigate:
```tsx
import { Form, useNavigation } from "react-router";
function NewProjectForm() {
const navigation = useNavigation();
// Get optimistic value from submission
const optimisticTitle = navigation.formData?.get("title");
const isSubmitting = navigation.state === "submitting";
return (
<Form method="post">
<input type="text" name="title" />
<button disabled={isSubmitting}>
{isSubmitting ? "Creating..." : "Create"}
</button>
{optimisticTitle && <p>Creating "{optimisticTitle}"...</p>}
</Form>
);
}
```
## Skeleton Loading
Show skeletons while data loads:
```tsx
import { Suspense } from "react";
import { Await } from "react-router";
export async function loader() {
return {
fastData: await getFastData(),
slowData: getSlowData(), // Don't await
};
}
export default function Page({ loaderData }: Route.ComponentProps) {
return (
<div>
<h1>{loaderData.fastData.title}</h1>
<Suspense fallback={<CommentsSkeleton />}>
<Await resolve={loaderData.slowData}>
{(data) => <Comments data={data} />}
</Await>
</Suspense>
</div>
);
}
```
## Disabling During Submission
Prevent double submissions:
```tsx
function ContactForm() {
const navigation = useNavigation();
const isSubmitting = navigation.state === "submitting";
return (
<Form method="post">
<input type="text" name="message" disabled={isSubmitting} />
<button type="submit" disabled={isSubmitting}>
{isSubmitting ? "Sending..." : "Send"}
</button>
</Form>
);
}
```
## Busy Indicators with CSS
Use CSS for simple loading indicators:
```css
.loading {
opacity: 0.5;
pointer-events: none;
}
```
```tsx
<body className={isNavigating ? "loading" : ""}>
```
---
## See Also
- [actions.md](./actions.md) - Form handling and useFetcher patterns
- [special-files.md](./special-files.md#customizing-roottsx-complete-example) - Global loading indicators in root.tsx
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |