ErrorBoundary

Wrap anything that can fail. While nothing has thrown, the boundary renders its content and no element of its own; the first exception replaces that content with the default error UI - the illustration, the title, and a footer offering to reload the page, to leave for the home page, or to simply try rendering the content again.

Title replaces the default heading and Message adds a line under it. The title says that something broke; the message is where whoever is looking at the screen is told what it means for them and what to do next, which is the difference between an error page that reads as an apology and one that reads as an instruction.

ShowException renders the exception's full text - message, type and stack trace - under the title, in a block that scrolls and takes the keyboard focus so it stays reachable. ShowCopyButton puts that same text on the clipboard instead, which is what turns a screenshot of an error into something searchable in a bug report; the button says CopiedText for a moment afterwards, since a copy leaves nothing else on the screen to show for itself. Both are what a developer needs while building and internal detail in front of a user once the app is deployed, so both are off by default and belong behind an environment check.

The built-in illustration is drawn in the theme's error color, so it re-skins with everything else. IconName swaps it for a glyph of the Fluent icon set, IconTemplate for markup of your own, and HideIcon drops it altogether - which is what a boundary around a small region wants, where a 64 pixel illustration is louder than whatever failed.

The three default actions are independent. Refresh reloads the page in the browser, Home navigates to HomeUrl (the site root unless you name another), and Recover clears the error and renders the content again - so it only helps once whatever threw has been put right, which is why it is the one to hide when nothing about the failure will have changed by the time the reader clicks it. Each has its own text parameter and its own Hide...Button, the Copy button joins them in the same row wherever ShowCopyButton is set, and AdditionalButtons appends to the row rather than replacing it.

Footer replaces the whole row of default buttons while keeping the icon, the title and the message of the default UI - the middle ground between accepting the built-in actions and writing the error UI from scratch. What it replaces is the buttons and not the row: it is rendered in the same footer element they were laid out in, so it keeps their wrapping row and is reached by Classes.Footer and Styles.Footer exactly as they are. A boundary that sets it never renders AdditionalButtons.

ErrorTemplate replaces the error UI outright and is handed a context carrying the exception along with the boundary's own Recover, Refresh and GoHome actions, so a retry button is one @context.Recover away with no component reference to wire up. The inherited ErrorContent template still works and receives the exception alone; where both are set, ErrorTemplate wins.

OnError runs before the error UI is rendered, which is where the exception is reported to whatever collects them, and OnRecover runs on every route back out of the errored state - the Recover button, the Recover method, RecoverKeys and RecoverOnNavigation alike. Which of them it was arrives as a BitErrorBoundaryRecoverReason, since a reader who asked to try again is waiting for something to happen while a boundary that cleared itself is not. The boundary also logs through the app's IErrorBoundaryLogger, exactly as Blazor's own boundary does; NoLogging turns that off where OnError already reports the exception elsewhere.

Caught: 0  |  Recovered: 0  |  Last error: -  |  Last recovery: -

A boundary only ever sees what the renderer routes to it, which leaves out everything thrown where nothing is awaiting it - a fire-and-forget task, a timer, a JS interop callback, an exception a page caught itself and wants shown. Capture hands the boundary one of those and puts it into exactly the state a caught exception would: logged, reported through OnError, counted against MaximumErrorCount and rendered. Reach the boundary through @ref, or - since it cascades itself to its content - through a cascading parameter from anywhere inside it, which is the Blazor counterpart of React's showBoundary. Use CaptureAsync off the renderer's thread.

An errored boundary keeps showing its error UI until something clears it, and what makes the content worth rendering again is usually a change somewhere else - a different record selected, a filter reset, a retry counter bumped. List those values in RecoverKeys and the boundary recovers itself the moment any of them differs from what it last saw, which is React's resetKeys without the component reference.

Selected record: 1

A boundary wrapping the body of a layout outlives the page that threw, so without help its error UI stays on screen wherever the reader goes next. RecoverOnNavigation clears it on the next location change, which is what makes a single app-wide boundary usable. A narrowly scoped boundary has no use for it - it is torn down with the page it belongs to.

The error UI is an assertive live region with the alert role, so a screen reader announces it where it appeared - the content it replaced is gone and nothing else on the page says so. AutoFocus also carries the reader to it, which is what a boundary around a whole page wants, where whatever had the focus went with the content. The exception block scrolls and holds nothing that can take the focus, so it takes it itself and is named as a region by ExceptionLabel; an empty label drops the name and the role with it. Every one of the underlying attributes - role, aria-live, aria-atomic, tabindex - can be written as a plain HTML attribute on the boundary, and what you write wins over what the boundary would have written.

The icon also takes a BitIconInfo, which renders whatever CSS classes an external library needs. Use the Fa, Bi and Css helpers, or pass the classes as a plain string.

Style and Class land on the root of the error UI, and Styles and Classes reach each part of it by name - the icon, the title, the message, the exception block, the footer and each of its buttons. None of them touch the boundary's own content: while nothing has been caught there is no element of the boundary's to style.

Use BitErrorBoundary in right-to-left (RTL).