React 18 APIs
startTransition, useTransition, useDeferredValue, useId, useSyncExternalStore, and useInsertionEffect — when each one is the right tool. · 5 lessons · click a card to expand
Part of the React 16 → 19.3 evolution reference. Expand a card, then use chapter links in the sidebar.
Architecture: Concurrent Rendering. This page is how to use the APIs. Each major hook has three different product examples.
startTransition and useTransition
1 item01useTransition marks a setState as non-urgentReact 18
useTransition returns [isPending, startTransition]. Updates inside startTransition are interruptible. isPending is true until that transition’s render commits.startTransition (imported from react) is the same marking function without isPending. Use the hook when the UI should reflect “still switching.”What is it?
import { useState, useTransition } from "react";
function Tabs({ panels }) {
const [tab, setTab] = useState("overview");
const [isPending, startTransition] = useTransition();
function select(next) {
startTransition(() => setTab(next));
}
return (
<>
{panels.map((p) => (
<button key={p.id} onClick={() => select(p.id)} disabled={isPending && tab !== p.id}>
{p.label}
</button>
))}
{isPending ? <span>Loading view…</span> : null}
<HeavyPanel id={tab} />
</>
);
}import { useState, useTransition } from "react";
const PANELS = [
{ id: "overview", label: "Overview" },
{ id: "revenue", label: "Revenue" },
{ id: "cohorts", label: "Cohorts" },
];
function HeavyPanel({ id }) {
const rows = Array.from({ length: 40 }, (_, i) => `${id} metric ${i + 1}`);
return (
<ul>
{rows.slice(0, 8).map((row) => (
<li key={row}>{row}</li>
))}
</ul>
);
}
export default function DashboardTabs() {
const [tab, setTab] = useState("overview");
const [isPending, startTransition] = useTransition();
return (
<div>
{PANELS.map((panel) => (
<button
key={panel.id}
onClick={() => startTransition(() => setTab(panel.id))}
disabled={isPending && tab !== panel.id}
>
{panel.label}
</button>
))}
{isPending ? <p>Loading view…</p> : null}
<HeavyPanel id={tab} />
</div>
);
}Click Run to render this example.
Why was it introduced?
Urgent input and heavy views shared one update pipeline. See Concurrent.
Before React 18
function select(next) {
setTab(next); // whole tree waits; or you fake it with local `loading` + debounce
}Teams invented const [pending, setPending] = useState plus setTimeout to paint a spinner — not interruptible, not coordinated with Suspense.
With useTransition
React knows the in-flight tree can be abandoned if the user clicks another tab.
How it works
startTransition(fn) runs fn immediately. Any setState inside is tagged as a transition lane. React may keep the current UI on screen (isPending === true) until the new tree is ready. Nested useDeferredValue also participates in this model.
Real-world examples
1. Search / filter a large catalog (e-commerce)
Problem: 8,000 product cards. Each keystroke must not stall the search box.
function Catalog({ products }) {
const [input, setInput] = useState("");
const [query, setQuery] = useState("");
const [isPending, startTransition] = useTransition();
return (
<>
<input
value={input}
onChange={(e) => {
const v = e.target.value;
setInput(v);
startTransition(() => setQuery(v));
}}
/>
<div style={{ opacity: isPending ? 0.6 : 1 }}>
<ProductGrid products={products.filter((p) => p.name.includes(query))} />
</div>
</>
);
}import { useMemo, useState, useTransition } from "react";
const PRODUCTS = Array.from({ length: 80 }, (_, i) => ({
id: String(i),
name: ["Mug", "Lamp", "Chair", "Desk", "Plant"][i % 5] + " " + (i + 1),
}));
export default function ProductFilter() {
const [input, setInput] = useState("");
const [query, setQuery] = useState("");
const [isPending, startTransition] = useTransition();
const visible = useMemo(
() => PRODUCTS.filter((p) => p.name.toLowerCase().includes(query.toLowerCase())),
[query],
);
if (input.toLowerCase() === "boom") {
throw new Error("Type something else — this is a preview error.");
}
return (
<div>
<input
value={input}
placeholder="Filter products (try boom for an error)"
onChange={(e) => {
const value = e.target.value;
setInput(value);
startTransition(() => setQuery(value));
}}
/>
<p style={{ opacity: isPending ? 0.6 : 1 }}>
{visible.length} matches
</p>
<ul style={{ opacity: isPending ? 0.6 : 1 }}>
{visible.slice(0, 8).map((product) => (
<li key={product.id}>{product.name}</li>
))}
</ul>
</div>
);
}Click Run to render this example.
Useful here: the input stays urgent; the grid is the transition.
2. Tab switching in an analytics dashboard
Problem: “Revenue” vs “Cohorts” mounts different 200kb chart trees.
startTransition(() => setTab("cohorts"));Keep the old chart visible (isPending) instead of unmounting to a blank null.
3. Navigation-style content in an SPA (settings sections)
Problem: clicking “Billing” should feel instant on the nav item, while the billing form (with many fields) can lag by a frame.
function SettingsNav({ current, onChange }) {
const [isPending, startTransition] = useTransition();
return (
<nav aria-busy={isPending}>
{items.map((id) => (
<button
key={id}
aria-current={current === id}
onClick={() => startTransition(() => onChange(id))}
>
{id}
</button>
))}
</nav>
);
}When should I use it?
Heavy CPU renders triggered by a click/type where you can split “immediate feedback” from “next view.”
When should I NOT use it?
- The state is the controlled input
- Updates that must commit in order with layout (
flushSyncterritory) - Treating
isPendingas “fetch still in flight” without Suspense — it only tracks React render of that transition
Common mistakes
// WRONG: input is also deferred
startTransition(() => setInput(e.target.value));// WRONG: wrapping fetch
startTransition(async () => {
const data = await fetch("/api"); // the await is NOT a React transition
setData(data);
});startTransition does not wait for promises (React 19 Actions do a better job for async functions). In 18, do the fetch yourself, then startTransition(() => setData(data)) if the commit is heavy.
Performance considerations
Improves interaction responsiveness. Does not shrink bundle size.
Related APIs
startTransition (no pending flag), useDeferredValue, Suspense, React 19 Actions
Interview notes
isPending= transition render not committed yet.- Do not put the text input’s value only inside the transition.
- 18 API; concurrent root required.
opacity) when isPending — a cheap UX that signals “this is old.”useDeferredValue
1 item02useDeferredValue lags a value so urgent UI can update firstReact 18
useDeferredValue(value) returns a deferred copy that may still be the previous value during urgent updates.useStates. One state; React defers the expensive consumers.What is it?
function Search({ items }) {
const [query, setQuery] = useState("");
const deferredQuery = useDeferredValue(query);
const stale = deferredQuery !== query;
const results = useMemo(
() => items.filter((item) => item.name.includes(deferredQuery)),
[items, deferredQuery],
);
return (
<>
<input value={query} onChange={(e) => setQuery(e.target.value)} />
<ul style={{ opacity: stale ? 0.6 : 1 }}>
{results.map((item) => (
<li key={item.id}>{item.name}</li>
))}
</ul>
</>
);
}import { useDeferredValue, useMemo, useState } from "react";
const ITEMS = Array.from({ length: 60 }, (_, i) => ({
id: String(i),
name: ["Alpha", "Bravo", "Charlie", "Delta"][i % 4] + " " + (i + 1),
}));
export default function DeferredSearch() {
const [query, setQuery] = useState("");
const deferredQuery = useDeferredValue(query);
const stale = deferredQuery !== query;
const results = useMemo(
() => ITEMS.filter((item) => item.name.toLowerCase().includes(deferredQuery.toLowerCase())),
[deferredQuery],
);
return (
<div>
<input
value={query}
placeholder="Filter the list"
onChange={(e) => setQuery(e.target.value)}
/>
<ul style={{ opacity: stale ? 0.6 : 1 }}>
{results.slice(0, 8).map((item) => (
<li key={item.id}>{item.name}</li>
))}
</ul>
</div>
);
}Click Run to render this example.
Why was it introduced?
useTransition needs two state variables if the urgent value and the heavy value are the same conceptually. useDeferredValue is “please use the old value for expensive children until you can catch up.”
Before React 18
Debounce query with setTimeout (feels laggy, skips values) or useMemo on the hot path (still runs on the same urgent render).
How it works
During an urgent render, React may pass the previous deferred value to children. A later render updates it. Similar to a transition, but driven by a value instead of a setState wrapper.
Real-world examples
1. Autocomplete (SaaS command palette)
Problem: filtering commands is CPU-heavy; the field must stay in sync.
const deferred = useDeferredValue(query);
<CommandList query={deferred} />2. Live preview of a newsletter (marketing tool)
Problem: the HTML preview reflows slowly; the textarea is urgent.
const deferredHtml = useDeferredValue(html);
<Preview html={deferredHtml} />3. Map markers from a filter (logistics dashboard)
Problem: re-clustering 20k points is expensive.
const deferredBounds = useDeferredValue(bounds);
<MarkerLayer bounds={deferredBounds} />When should I use useDeferredValue vs useTransition?
| Prefer | When |
|---|---|
useTransition | You control the setState (tab click, navigation) and want isPending |
useDeferredValue | A value already exists (from props or one useState) and a child is expensive |
They can combine. Do not stack them meaninglessly.
When should I NOT use it?
Cheap lists. Values that must never be stale (prices at click-to-buy — do not defer the SKU the user clicked).
Common mistakes
- Deferring the
<input value={deferred}>— the field lags - Forgetting
useMemoon the expensive derive — you still compute on the urgent render if you filter withqueryinstead ofdeferredQuery
Performance considerations
Same as transitions: responsiveness, not less work overall.
Related APIs
useTransition, memo on the heavy child (so it skips when deferred value is unchanged)
Interview notes
- Deferred value may be stale by design.
- Compare
deferred !== valuefor a pending UI. - React 18.
memo(ProductGrid) + deferred props is the usual combo.query and deferredQuery on each render while typing fast.useId
1 item03useId generates stable unique IDs for accessibility and SSRReact 18
useId() returns a unique string stable across server and client for that component instance. Use it to wire htmlFor / id / aria-describedby.Math.random() and incrementing counters mismatch on hydration.What is it?
function Field({ label, error }) {
const id = useId();
const errorId = `${id}-error`;
return (
<div>
<label htmlFor={id}>{label}</label>
<input id={id} aria-describedby={error ? errorId : undefined} />
{error ? <p id={errorId}>{error}</p> : null}
</div>
);
}Why was it introduced?
SSR + lists of inputs: server said id="1", client said id="2" after a diverging render. Hydration warnings and broken labels.
Before React 18
let c = 0;
function useBrokenId() {
const ref = useRef(null);
if (!ref.current) ref.current = `field-${c++}`;
return ref.current;
}This breaks if server and client increment differently, or if Strict Mode double-invokes.
How it works
React generates an ID from the tree position (and a root prefix). Same tree → same ID on server and client.
Do not use useId as a React key. Keys must come from your data.
Format changes (know this so CSS does not surprise you)
| Version | Example shape (simplified) |
|---|---|
| 18.0 | :r1: (colon — invalid in CSS selectors / `querySelector`) |
| 19.1 | «r1» (valid in CSS) |
| 19.2 | prefix _ (underscores instead of colons in the default prefix) |
If you concatenated useId() into a CSS selector on React 18, it could fail. Prefer document.getElementById or refs, not CSS selectors, for these IDs.
Real-world examples
1. Checkout form — every AddressField instance needs unique label/input ids.
2. Modal in a design system — aria-labelledby pointing at the title id.
3. Password field with “show” toggle — describe the toggle with aria-controls={inputId}.
When should I use it?
Accessibility relationships. SSR-safe ids.
When should I NOT?
- List
keys - Database ids
- CSS module class names
Common mistakes
- Calling
useIdin a loop instead of in a child component - Assuming the string format is stable across React minors (it is not; see table)
Related APIs
19.1 / 19.2 useId format notes, identifierPrefix on createRoot / hydrateRoot for multiple roots on one page
Interview notes
- Hydration-safe ids.
- Not for keys.
- Format changed in 19.1 and 19.2.
identifierPrefix: 'dash-' so ids do not collide.id equals client id.useSyncExternalStore
1 item04useSyncExternalStore subscribes to external stores without tearingReact 18
window.matchMedia, a WebSocket module) under concurrent rendering.useEffect + useState subscriptions can tear: one component sees store version A, another sees B in the same paint, because concurrent render interleaved with a store update.What is it?
function useOnlineStatus() {
return useSyncExternalStore(
(onStoreChange) => {
window.addEventListener("online", onStoreChange);
window.addEventListener("offline", onStoreChange);
return () => {
window.removeEventListener("online", onStoreChange);
window.removeEventListener("offline", onStoreChange);
};
},
() => navigator.onLine,
() => true, // server snapshot
);
}Signature: useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot?).
getSnapshot must return an immutable value. If you return a new object every call, you infinite-loop.
Why was it introduced?
Concurrent rendering reads the store at different times during one render pass. This hook forces a consistent snapshot or retriggers.
Before React 18
const [online, setOnline] = useState(true);
useEffect(() => {
const on = () => setOnline(navigator.onLine);
window.addEventListener("online", on);
return () => window.removeEventListener("online", on);
}, []);Fine on React 17. Can tear on 18 concurrent.
Real-world examples
1. Redux / Zustand selector — libraries already wrap this hook. You call useSelector. Under the hood: useSyncExternalStore.
2. `prefers-reduced-motion` in a design system
function usePrefersReducedMotion() {
return useSyncExternalStore(
(cb) => {
const m = window.matchMedia("(prefers-reduced-motion: reduce)");
m.addEventListener("change", cb);
return () => m.removeEventListener("change", cb);
},
() => window.matchMedia("(prefers-reduced-motion: reduce)").matches,
() => false,
);
}3. Chat connection singleton — module-level client.getStatus() with client.subscribe(cb).
When should I use it?
Any external mutable store. Browser APIs that change over time. Library authors must use it; app authors often use it indirectly.
When should I NOT?
React state (useState) is already inside React. Do not mirror React state through an external store “for concurrent safety.”
Common mistakes
getSnapshotreturningstore.getState()object that is a new identity every time- Omitting
getServerSnapshotand hydratingnavigator.onLinemismatches
Related APIs
useEffect subscriptions (legacy), Redux useSelector
Interview notes
- Prevents tearing with concurrent renders.
getSnapshotreferential stability.- 18.
useStore for a module singleton, this is the hook, not useEffect.useInsertionEffect
1 item05useInsertionEffect injects CSS before layout effectsReact 18
DOM update → useInsertionEffect → useLayoutEffect → paint → useEffectWhat is it?
// Library code, not app code
useInsertionEffect(() => {
if (!document.getElementById(ruleId)) {
const tag = document.createElement("style");
tag.id = ruleId;
tag.textContent = `.${className}{color:red}`;
document.head.appendChild(tag);
}
}, [ruleId, className]);Why was it introduced?
useLayoutEffect in a styled component ran after a child useLayoutEffect that measured width — too late; the CSS was not in the document yet. useInsertionEffect fires earlier and does not have access to refs (by design).
Before React 18
CSS-in-JS used useLayoutEffect or rendered <style> tags and hoped.
Real-world examples
These are library scenarios:
1. Emotion / styled-components inserting a rule before a popover measures itself.
2. A runtime theme package injecting CSS variables on the root before layout.
3. CSS Modules runtime (rare) — dynamic style tags.
When should I use it in an application?
Almost never. If you are not writing a styling library, skip it.
When should I NOT?
- Data fetching
- Event listeners
refaccess (not allowed the same way; this effect is not for DOM measurement)
Common mistakes
Using it as a “faster useLayoutEffect.” It is not. It has stricter rules (no subscribing, no refs).
Interview notes
- For CSS-in-JS authors.
- Runs before layout effects.
- 18.
useEffect.