shadcn.io is not affiliated with official shadcn/ui
Error Troubleshooting Steps Block for React
A full-height error page for a video-call app that walks you through four fixes: a Try again that honestly keeps failing, ticked steps each with a why and a How, a four-part bar, and a Still stuck note that switches on when all four are ticked.
Installation
Overview
Help visitors fix a connection error themselves before they write in, with this troubleshooting error block for React with Base UI. It's the error screen of Callwick, a video-call app: the page's two side rails run its full height, and one band crosses the screen between two rules with a plus mark where each meets a rail. The product's mark sits over the heading "We can't connect your call" and one sentence, and the Shine Button "Try again" comes straight after, first in the focus order. Under a rule, "Things to try" lists four steps as real Checkboxes: Check your connection, Clear your cache, Turn off extensions and Try another browser. Each has a line on why it helps and a Collapsible "How" with the detail. A four-part bar and the count "2 of 4 tried" follow the ticks, and a Reset clears them. Once all four are ticked, an Alert "Still stuck?" with a support link switches on in the room it has held since load, so the page never changes height when it appears. It's built from Checkbox, Collapsible, Alert, Shine Button, Button, Field and Guides, with a CSS entrance only. For the error page of any app that people can partly fix themselves.
FAQ
What do Try again and the ticks do, and what stays in the page?
Nothing leaves the page. Try again shows a spinner on the button for under a second, then a polite status line says "Still can't connect, in this demo" and that nothing was requested; it never succeeds by accident. Ticks are kept in the page's state only: they aren't saved, and nothing is checked on the visitor's behalf. To wire Try again for real, reconnect to your service where the code says so, keep the busy state until it answers and show the page again when it succeeds.
How do I change the steps?
Edit STEPS: each has an id, a name, one line on why it helps and a longer how. The count, the four-part bar (one part per step) and the "Still stuck?" condition all follow the length of the list, so add or remove a step without touching anything else. Keep each step something a visitor can do in a minute, and keep the order from most to least likely.
Why is Try again above the checklist?
Because it is the page's one primary action, and a visitor on a phone should reach it without scrolling past four rows. The steps are help for when it keeps failing, not a gate in front of it. The button stays first in the focus order, so a keyboard user hits it before the list.
When does Still stuck? appear, and why doesn't it move the page?
When all four steps are ticked. Its room is reserved from the start, hidden and unreachable by keyboard until then, so switching it on changes no layout and no tab order. To show it earlier, change the complete condition, for example after two steps or after a failed retry.
Is it usable with a keyboard and a screen reader?
Each step is a real checkbox named by its title and described by its why line; Space ticks it, and the polite status line reads "Clear your cache marked as tried. 2 of 4 tried." The How buttons say which step they belong to and whether they're open. The four-part bar is decoration: the count in words says the same. Tried is a filled box, a filled part of the bar and a word, never only a color.
Related
- Pro
Error Support Channels
Help and supportA full-height error page for a handmade-goods marketplace that sends you to a person: three channels with their real cost in time, and a composer whose heading and button follow the channel and that attaches the error details.
- Pro
Error Feedback Form
Help and supportA full-height error page for a document-export tool that asks what you were trying to do: quick-pick chips that start the message, a checked message and optional email, and a thank-you that replaces the form in place.
- Pro
500 Server Error
Server and outagesA full-height 500 page for an event-ticketing site: the heading, a copyable reference and time, a Try again that honestly keeps failing, and a framed figure of the request's path with the failed stop marked.
- Pro
Error Debug Logs Window
In-app errorsA debug-log viewer for an API monitoring tool, as a fixed-height app window: a Critical badge and copyable error id, a level filter with counts, eight log lines with the failing one marked, and a foot that copies, downloads and reports.
- Pro
Request Timeout Error
Server and outagesA full-height 408 page for a report generator: a request waterfall on a fixed time axis with a cut line at the wait you choose, a verdict that says whether the answer would have arrived, and a Retry that names the wait.
- Pro
Server Error Incident Card
Server and outagesA server-error panel for a studio-booking app: a card of what the page knows (error type, time, a copyable request id, retries) and what you can do, with a Retry that adds a typed retry and keeps failing.