Overlays + Async Data (React Query)
Opening a floating overlay (a Sheet, a Dialog, or an AlertDialog) is a navigation: the user has already committed to seeing more context by clicking the trigger. When the overlay's body needs remote data, fetching before opening turns a 404 or 500 into a silent drop back to the parent view, and a spinner on the trigger leaves the click feeling unregistered. This recipe mounts the shell immediately and resolves data inside it, so every click produces forward motion and every error stays in the place the user navigated to.
The pattern is identical across all three overlays: only the shell changes. The query hook, the body-state components, and the retry policy below are shared verbatim; the demo lets you host them in any of the three shells.
Try it in the live demo, directly above the code that renders it.
Why open the overlay first?
- The open should feel instant, especially on slow networks. The user already committed to the navigation by clicking the trigger. Waiting for the request to resolve before opening means dead air at the parent view, and the wait scales with request latency: long-running endpoints or slow connections turn into seconds where users can't tell whether the click registered. Mounting the shell immediately decouples click feedback from request time.
- No flashing across the open → load → close → reopen cycle. Within a single open, only the overlay's
Bodyregion branches between pending, success, and error, so header, close, and footer stay mounted and layout shift is contained to one region. Across opens, TanStack Query's cache lets a re-trigger after a successful fetch skip the pending state entirely; fetch-then-open does the opposite, re-running the request on every trigger and flashing the chrome in only after each fetch resolves. - Errors stay where the user intended to be. An inline error inside the overlay preserves the navigation and keeps recovery actions in reach. Closing on error forces a re-trigger and re-orientation from the parent view.
- Actions gate on data, not hope. The footer's primary action ("Save changes" in a sheet or dialog, the destructive confirm in an alert dialog) stays disabled until the query succeeds. This matters most for
AlertDialog: confirming a destructive action against a record that failed to load is never safe. - Retry is a product decision, not a default. Transient
500responses are worth another attempt; a definitive404is not. The query hook owns that policy so the view stays free of conditional retry logic and the intent stays reviewable in one place.
What this covers
The demo's segmented control picks which shell hosts the async body; the same three scenarios run identically in a Sheet, a Dialog, and an AlertDialog.
The route is also available as plain markdown at /recipes/overlay-async.md, so humans and LLM tools can fetch the same recipe without scraping the rendered page.
Anatomy
Implementation
The "Why" section above is the user-perceived case for the pattern. These rules are how to wire it up so the code stays consistent with that intent.
- Mount the overlay on the click event. Set selection state synchronously in the handler; never gate it on a fetch result.
- Branch only the body on query state.
query.isPending,query.isError, andquery.isSuccessbelong inside the overlay'sBodyregion. Header, close button, and footer stay outside the conditional. - Factor the query into a hook.
useUserQueryowns fetching, retry, stale-time, and cancellation. The components that render query results (the shells,UserDetailsBody) consume aUseQueryResultand never reach into TanStack Query directly. The cache-observability bits inUserOverlayDemo(theuseQueryClientsubscription andremoveQueriesreset) are demo-only; production overlays shouldn't touch the cache. - Encode the retry policy in
useQuery. Returnfalsefromretryfor terminal errors like404. Return a boundedfailureCountcheck for transient ones like500. - Match the retry UI to the retry policy. Show a retry button on recoverable errors. Omit it on terminal ones: retrying a definitive not-found adds latency without recovery.
Complete recipe
The worked example below uses Sheet as the shell; the next section shows the Dialog and AlertDialog shells consuming the exact same hook and body components. Copy the UI recipe into a client component that already has a QueryClientProvider mounted near the app root. The demo-only mock API is shown in the appendix below; in production, replace that import with your real API client and error type.
What transfers is the structure: the synchronous mount, the single branching region, the hook-owned retry policy, and the success-gated actions. What doesn't is the markup inside each state: UserDetails, the skeleton shapes, and the header/footer copy are demo content standing in for your real UI.
Swapping the shell
Everything above the shell (useUserQuery, UserDetailsBody, the loading/error/success components, the retry policy) is overlay-agnostic. To host the same async body in a different overlay, swap only the shell component. The live demo at the top of this page renders all three shells from the same parent selection state behind a segmented control.
Dialog
The Dialog shell is a one-for-one structural swap with Sheet: header and footer stay mounted, only Dialog.Body branches, and the primary action gates on query.isSuccess.
AlertDialog
An AlertDialog confirms a consequential (usually destructive) action, which sharpens the pattern's stakes: the record the user is about to act on is exactly the thing being fetched. Two rules are non-negotiable here:
- The destructive
Actionstays disabled until the query succeeds. Confirming against a record that hasn't loaded (or definitively doesn't exist) is never safe. On a 404, the disabled action plus the inline not-found state is the correct terminal UI. - Errors never auto-close the confirmation. The user chose to act; an inline error with a retry (for transient failures) keeps them in that intent instead of silently dropping it.
Mock API appendix
The code above imports a mock API module so the overlays can demonstrate happy, 404, and 500 states without a backend. In production, replace this file with your real API client and preserve the same query behavior: accept signal, throw typed errors, and let the UI decide which errors are retryable.
Production notes
- Keep each overlay shell in one component and keep API details behind
fetchUseror your app's equivalent data client. The shell is the only overlay-specific code; everything else is shared. - Use the
signalargument from TanStack Query'squeryFnwhen your API client supports cancellation. - Tune
retryby status code. This demo does not retry 404 because the server already answered definitively. Retry not-found responses only when eventual consistency is expected. - Gate footer actions on
query.isSuccess. ForAlertDialogspecifically, never enable the destructiveActionwhile the query is pending or errored: the confirmation is only meaningful against loaded data. - Let
staleTimeandgcTimegovern cache lifetime; the overlay does not need to manually evict on close. The demo's "Clear cache" button only exists to make the cache state observable in docs; production overlays typically don't surface a manual reset. - Prefer explicit query state branches here over
useSuspenseQuery. Suspense works, but error recovery requires an additional reset boundary and is harder to copy into route-controlled overlays.