Skip to content
Skills Library
Programming · Building & coding

optimistic-ui

/optimistic-ui

Default to optimistic-UI patterns where perceived speed matters. Render from cached state immediately, mutate optimistically with rollback, don't gate render on session validation, and never let heavy synchronous work sit between an input and the next paint. Applies to mutation handlers (save / edit / delete / toggle), list and detail views, dashboards, and any reactive UI measured against Linear / Superhuman / Raycast / Vercel-dashboard-class speed. The coding pattern at the component layer only, not a sync-engine, CRDT, or IndexedDB-architecture skill. Use when an interface feels slow, laggy

Repository
skills ↗
Licence
MIT
Last repository change
07.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 07.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Default to optimistic-UI patterns where perceived speed matters. Render from cached state immediately, mutate optimistically with rollback, don't gate render on session validation, and never let heavy synchronous work sit between an input and the next paint. Applies to mutation handlers (save / edit / delete / toggle), list and detail views, dashboards, and any reactive UI measured against Linear / Superhuman / Raycast / Vercel-dashboard-class speed. The coding pattern at the component layer only, not a sync-engine, CRDT, or IndexedDB-architecture skill. Use when an interface feels slow, laggy

Original author description

Default to optimistic-UI patterns where perceived speed matters. Render from cached state immediately, mutate optimistically with rollback, don't gate render on session validation, and never let heavy synchronous work sit between an input and the next paint. Applies to mutation handlers (save / edit / delete / toggle), list and detail views, dashboards, and any reactive UI measured against Linear / Superhuman / Raycast / Vercel-dashboard-class speed. The coding pattern at the component layer only, not a sync-engine, CRDT, or IndexedDB-architecture skill. Use when an interface feels slow, laggy

How it works

  1. Four places this default applies
  2. Granular reactivity makes optimistic updates feel right
  3. What this skill is not for
  4. Anti-patterns
  5. Review output contract
  6. Pre-ship check
Original SKILL.md headings · 146 lines, 1,590 words
SKILL.md preview
---
name: optimistic-ui
description: Default to optimistic-UI patterns where perceived speed matters. Render from cached state immediately, mutate optimistically with rollback, don't gate render on session validation, and never let heavy synchronous work sit between an input and the next paint. Applies to mutation handlers (save / edit / delete / toggle), list and detail views, dashboards, and any reactive UI measured against Linear / Superhuman / Raycast / Vercel-dashboard-class speed. The coding pattern at the component layer only, not a sync-engine, CRDT, or IndexedDB-architecture skill. Use when an interface feels slow, laggy, or sluggish on input (including a bad INP score), when deciding whether to show a spinner or loading state, or when asked for optimistic updates or Linear-class snappiness.
---

# Optimistic UI

The training-default React mutation handler is shaped like this:

```ts
async function save() {
  setLoading(true)
  await api.save(data)
  setLoading(false)
}
```

That shape gates the UI on the network. The user clicks; nothing visible happens; spinner; then the result lands. Across dozens of interactions a day, this is what "feels slow" actually means — not slow network, but a UI that waits for the network before moving.

**The attention shift this skill makes: the canonical view of the user's intent lives in the browser, not on the server. Write the local update first; treat the network as reconciliation, not gating.**

Apps that feel like Linear / Superhuman / Raycast share this default. The data architecture under it (IndexedDB, sync engines, CRDTs) is a separate decision — this skill is about the coding pattern at the component layer, which composes with whatever data layer the project has chosen.

## Four places this default applies

### 1. Mutations — apply local, queue async, rollback on reject

For any mutation the user initiates from the UI (toggle, status change, title edit, create, delete, save), the default shape is:

```ts
async function save(next: Item) {
  const prev = current
  setLocal(next)                          // 1. UI moves immediately
  try {
    await api.save(next)                  // 2. Network catches up
  } catch (err) {
    setLocal(prev)                        // 3. Rollback only on reject
    surfaceError(err)                     // 4. Tell the user it failed
  }
}
```

The rollback path is **mandatory, not optional**. Without it the UI silently diverges from the server on every failure and the user is acting on a lie.

Use this shape with whatever state lib the project uses. React Query: `useMutation({ onMutate, onError })` with `queryClient.setQueryData` / `queryClient.cancelQueries`. SWR: `mutate(key, optimisticData, { rollbackOnError: true })`. Zustand / Jotai / Redux / MobX: store update on the way in, store revert on the way out. The library doesn't matter; the four-step shape does.

### 2. Reads — render with what's cached, refetch in the background

The default training shape is `useEffect(() => fetch(...), [])` → spinner → render. The optimistic default: if cached data exists, render it immediately and refetch in the background. The spinner is reserved for the cache-empty case.

```ts
// Default — render blocked on fetch.
const { data, isLoading } = useQuery(['issues'], fetchIssues)
if (isLoading) return <Spinner />
return <List items={data} />

// Optimistic — render with cached, refetch quietly.
const { data } = useQuery(['issues'], fetchIssues, {
  initialData: () => cache.get('issues'),
  staleTime: 0,
})
return <List items={data ?? []} />
```

The empty-cache case is the only one that earns a skeleton (one that preserves layout, shown only past a ≥300ms threshold). Every other case should render-with-cached, not render-after-fetch.

### 3. Auth — assume the happy path, redirect on 401

The default training shape: validate session, *then* render. The optimistic shape: render if a local session token exists; let the first failed API call trigger redirect.

```ts
// Default — gated render.
const { user, isLoading } = useAuth()
if (isLoading) return <Spinner />
if (!user) redirect('/login')
return <App />

// Optimistic — assume valid, redirect on the rejection that actually comes.
const cached = localStorage.getItem('session')
if (!cached) redirect('/login')
return <App />  // API client will redirect on 401 if session is invalid
```

The cost of being wrong is one extra redirect after the first failed API call. The benefit is no perceptible pre-render gate on the common case (token present and valid).

This pattern needs the API client to handle 401 → redirect centrally. If the project doesn't have that, install it once — it pays back on every page.

### 4. Local heavy work — paint the feedback, then yield

The network isn't the only thing that gates the UI; a long main-thread task does the same with no spinner to blame. The user types in a filter box, the handler synchronously filters 10,000 rows, and the keystroke doesn't echo until the work finishes. This is what INP measures — the worst input-to-next-paint latency of the visit, good at ≤ 200ms (p75), budgeted roughly as input delay < 50ms + processing < 100ms + presentation < 50ms.

The same default applies: move the UI first, do the expensive part after the paint.

```ts
async function onFilterChange(query: string) {
  setQuery(query)                               // 1. Cheap visible update — keystroke echoes
  await yieldToBrowser()                        // 2. Browser paints it before we block
  setResults(expensiveFilter(query))            // 3. Heavy work after the paint
  requestIdleCallback(() => track('filter'))    // 4. Lowest-priority work when idle
}

const yieldToBrowser = () =>
  'scheduler' in window && 'yield' in scheduler
    ? scheduler.yield()                  // continuation resumes at boosted priority
    : new Promise(r => setTimeout(r, 0)) // fallback yields, but loses queue priority
```

In React, `useTransition` is this shape with the bookkeeping done: keep the input's own state update synchronous, wrap the expensive derived update in `startTransition(() => setResults(...))`. To find offenders in the field, the `web-vitals` attribution build's `onINP()` reports which script and which phase (input delay / processing / presentation) ate the budget.

## Granular reactivity makes optimistic updates feel right

Optimistic UI compounds with **granular subscriptions**. When 50 issues update in a batch, the result should be 50 cell re-renders, not one big list re-render. If the project's state library exposes per-field subscriptions (MobX observables, Solid signals, Jotai atoms, React Query per-key cache, Zustand selectors), use them — read one field, re-render on that field.

Avoid `useState` for shared data that several components read. Avoid passing whole objects down when only a property is read. Both create wide re-render cones that erase the smoothness the optimistic update was meant to deliver.

This is downstream of the main rule, not separate from it. An optimistic update on a non-granular store can still feel janky; granular reads without optimistic writes still wait on spinners. The combination is what feels Linear-fast.

## What this skill is *not* for

- **Server-rendered apps** where data lands in HTML on first paint. Optimistic patterns add complexity without the perceived-speed payoff — the server already moved the UI immediately.
- **Mutations with hard server-side preconditions** — payments, irreversible writes, regulatory checks, anything where "rollback the UI" isn't a real recovery. Use a confirmation dialog and a spinner here; optimism is dishonest when the server is the source of truth.
- **Sync engines / CRDTs / IndexedDB data architecture.** This skill is the *coding pattern* at the component layer. The data-architecture decision (Linear's sync engine, ElectricSQL, Replicache, Yjs, Automerge) is a separate, much larger commitment. If the user is asking about *that*, recommend they treat it as an architecture spike, not a skill invocation.
- **First-time UI for never-cached data.** A cold load has nothing local to render; a skeleton that preserves layout is correct here. This skill applies once the cache is warm — which is most of the lifetime of a session.

## Anti-patterns

- **`setLoading(true)` before a mutation.** The UI should already have moved. If you're reaching for a loading flag on a write, the local update is missing.
- **`if (isLoading) return <Spinner />` at the top of a component that has cached data available.** That's gating render on a fetch that has nothing new to add.
- **Rolling back silently.** A failed mutation needs a visible signal — toast, banner, inline error. Otherwise the user thinks it succeeded and the lie compounds.
- **Optimistic updates without a rollback path.** "It usually works" isn't a recovery strategy. The rollback is what makes optimism honest.
- **Optimistic updates on irreversible operations.** If `rollback()` can't actually restore the prior state (because the server already charged the card, sent the email, deleted the record), don't pretend it can. Confirm first.
- **Whole-object subscriptions where a field would do.** `useStore()` returning the whole store and destructuring the field you need re-renders on every unrelated mutation. Use a selector.

## Review output contract

When reviewing existing UI code, present every change as a markdown table with **Before** and **After** columns — every change made or proposed, not a subset; never loose "Before:" / "After:" lines outside a table. Group changes by principle with a heading above each table, and keep each row to a single diff so the whole list scans quickly. Write every **After** snippet in the styling system the project already uses, carry the one-line reason with each row, and cite `file:line` when it isn't obvious from the snippet. A principle that was reviewed and needed nothing gets no table at all.

## Pre-ship check

Before saying "done" on a mutation, list, or auth flow:

- [ ] If the user initiates the mutation, the UI moves *before* the network call returns. No `setLoading(true)` between user click and visible state change.
- [ ] No heavy synchronous work between an input and the next paint — cheap state echo first, then yield (`scheduler.yield()` / `startTransition`), heavy work after.
- [ ] Every optimistic update has a rollback path. Failed-mutation case is exercised at least once mentally.
- [ ] Failed mutations surface a visible signal (toast, banner, inline error). Not just a silent revert.
- [ ] Reads check cached state first; only fall through to a skeleton/spinner on cold cache.
- [ ] Auth render isn't gated on an `isLoading` flag from a session-validation call. Local token presence is sufficient to render; 401 triggers redirect.
- [ ] Component subscribes to the narrowest slice of state it needs — selector / signal / per-key cache, not whole-store reads.
- [ ] Mutation isn't optimistic on irreversible operations (payments, sends, hard deletes). Confirmation + spinner here is correct.
Files in this package (2)
  • SKILL.md 11 KB
  • agents/openai.yaml 1 KB

Versions

RepositoryScoreLicence
This page · claudialnathan/skills100MIT
Amey-Thakur/AI-SKILLS90MIT

Database snapshot: 13.11.2026 · package version cc6067fd7973 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100crud-ui
    Use when a data-backed app needs a working interface — a list people can add to, edit, and delete from, with the states that make it feel finished. Pairs with data-modeling, which defines the entities; this covers the React side: optimistic updates, forms, loading / empty /…
  • 100speed-is-the-feature
    This skill should be used when the user is building or reviewing loading states, optimistic UI updates, skeleton screens, code splitting, lazy loading, or performance budgets. Covers perceived speed, bundle size optimization, INP targets, and any work where application…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.