Extras
ErrorBoundary
Bit.BlazorUI.Extras
BitErrorBoundary catches what the components inside it throw and renders a themed, accessible and recoverable error UI in their place, so one failure does not take the whole app down. It builds on Blazor's ErrorBoundary with a complete default UI, templates for every part, logging, callbacks, automatic recovery and a way in for the exceptions the renderer never sees.
Notes
To use this component, you need to install the
Bit.BlazorUI.Extras(opens in a new tab)
nuget package, as described in the Optional steps of the
Getting started page.
A boundary catches what its content throws while rendering, in a lifecycle method or in an event handler -
not what never reaches the renderer (a fire-and-forget task, a timer, a JS callback), which is what
Capture is for. Scope boundaries narrowly: the closer one sits to what failed, the more of the page survives.
Usage
Every example is live. Open its code to see exactly what produced the component running underneath.
Basic
Wrap anything that can fail. Until something throws, the boundary renders its content and nothing of its
own; then the default error UI takes the content's place.
Title & message
Title replaces the heading (an empty one drops it) and Message tells the reader what to do next.
Icon
IconName swaps the illustration for a Fluent glyph, IconTemplate for your own markup, and
HideIcon drops it - which suits a boundary around a small region.
Exception details
ShowException renders the full exception in a scrolling block, and ShowCopyButton copies it
for a bug report. Both expose internals, so keep them behind an environment check in production.
Actions
Refresh reloads the page, Home goes to HomeUrl and Recover renders the content
again. Each has its own text and Hide...Button parameter; AdditionalButtons appends to the
row, while Footer replaces it.
Error template
ErrorTemplate replaces the whole error UI and receives a BitErrorBoundaryContext:
the exception plus the Recover, Refresh and GoHome actions. It wins over the inherited
ErrorContent.
Events
OnError runs before the error UI renders - report the exception there. OnRecover runs on every
way out and says which one through BitErrorBoundaryRecoverReason.
The boundary also logs through IErrorBoundaryLogger unless NoLogging is set.
Caught: 0 | Recovered: 0 |
Last error: - | Last recovery: -
Capture
What is thrown where nothing awaits it - a fire-and-forget task, a timer, a JS callback - never reaches a
boundary. Capture hands it over, through @ref or through the boundary cascaded to its
content; use CaptureAsync off the renderer's thread.
Automatic recovery
RecoverKeys recovers the moment one of its values changes, such as the selected record.
RecoverOnNavigation recovers on the next location change, which a boundary around a layout's body needs.
Accessibility
The icon, title and message are an alert, announced as they appear, inside a group named by the title
and described by the message. AutoFocus moves the focus to that group, which announces it instead.
A role or aria-live of the page's own on the boundary makes it the live region in place of the alert.
HeadingLevel fits the title into the page outline and ExceptionLabel names the focusable
exception block.
Cascading parameters
BitParams carries a BitErrorBoundaryParams to every boundary
under it - wrap a layout's body to set the texts, buttons and look of all of them once. These are defaults:
a parameter a boundary sets itself wins.
External Icons
Icon takes a BitIconInfo for external icon libraries: use the Fa, Bi and
Css helpers, or pass the classes as a plain string.
Style & Class
Style and Class land on the root of the error UI; Styles and Classes reach each
part by name. The CSS variables inherit, so one set on
:root or an ancestor restyles every boundary below it.
RTL
Use BitErrorBoundary in right-to-left (RTL).
CSS variables
The public custom properties this component reads off its root, for what no parameter covers.
Every variable is read with a fallback and never declared by the component, so it inherits like any other custom property:
set one on :root (or in a [bit-theme] block) to restyle every instance, on any ancestor to restyle the ones inside it,
or on the Style of one instance to restyle it - and any instance nested inside it, which inherits the value too; a parameter changes one alone,
as does the real CSS property on the instance's Style / Styles when that property does not inherit (opacity: 1 keeps
one disabled instance undimmed without undimming a disabled one inside it), while an inherited one such as color or
font-family also reaches the nested instances that do not set it themselves. Leave a variable unset and the component
falls back to the theme token beside it.
BitErrorBoundary CSS variables
| Name | Default value | Description |
|---|---|---|
| --bit-ErrorBoundary-background | --bit-clr-bg-pri | Background of the error UI. |
| --bit-ErrorBoundary-border | none | Border of the error UI. |
| --bit-ErrorBoundary-radius | --bit-shp-radius-none | Corner radius of the error UI. |
| --bit-ErrorBoundary-padding | spacing(3) | Padding of the error UI. |
| --bit-ErrorBoundary-gap | spacing(2) | Room between the parts of the error UI. |
| --bit-ErrorBoundary-align | center | start, center or end: aligns the parts, their text and the footer buttons together. |
| --bit-ErrorBoundary-icon-color | --bit-clr-err | Color of the built-in illustration or of the icon. |
| --bit-ErrorBoundary-icon-size | 64px (illustration) / --bit-siz-icon-lg (icon) | Size of the built-in illustration or of the icon. |
| --bit-ErrorBoundary-title-color | --bit-clr-err-fg | Color of the title. |
| --bit-ErrorBoundary-message-color | --bit-clr-fg-sec | Color of the message. |
| --bit-ErrorBoundary-message-max-width | 560px | Longest line of the message. |
| --bit-ErrorBoundary-exception-background | --bit-clr-bg-sec | Background of the exception details block. |
| --bit-ErrorBoundary-exception-color | --bit-clr-fg-sec | Text color of the exception details block. |
| --bit-ErrorBoundary-exception-font-family | --bit-tpg-font-family-mono | Font family of the exception details block. |
| --bit-ErrorBoundary-exception-max-height | 320px | Tallest the exception details block gets before it scrolls. |
API
Every parameter, public member, sub-class and enum this component exposes.
BitErrorBoundary parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| AdditionalButtons | RenderFragment? | null | The extra content of the footer of the boundary's default error UI, rendered after the Refresh, Home and Recover buttons. A boundary that sets Footer never renders it. |
| AutoFocus | bool | false | Moves the browser focus to the error UI as it appears, once per error, which then announces it in place of the alert. An error UI drawn by ErrorTemplate or ErrorContent has no element of the boundary's to move it to. |
| Body | RenderFragment? | null | Alias of the ChildContent. |
| ChildContent | RenderFragment? | null | The content the boundary renders and watches over while it has caught nothing. |
| Class | string? | null | The CSS class of the root element of the boundary's error UI. |
| Classes | BitErrorBoundaryClassStyles? | null | Custom CSS classes for different parts of the boundary's default error UI. |
| CopiedText | string? | null | The text the Copy button carries while what it copied is still on the clipboard. Defaults to "Copied". |
| CopyText | string? | null | The text of the Copy button. Defaults to "Copy details". |
| Dir | BitDir? | null | The text directionality of the boundary's error UI. |
| ErrorContent | RenderFragment<Exception>? | null | The inherited template of the error UI, receiving the caught exception alone. ErrorTemplate takes precedence over it. |
| ErrorTemplate | RenderFragment<BitErrorBoundaryContext>? | null | The template of the error UI, receiving the caught exception along with the boundary's own Recover, Refresh and GoHome actions. |
| ExceptionLabel | string? | null | The accessible name of the exception details block rendered by ShowException. Defaults to "Exception details", and an empty value drops the name and the region role with it. |
| Footer | RenderFragment? | null | The footer content of the boundary, replacing the default Refresh, Home and Recover buttons while keeping the footer element they are laid out in. |
| HeadingLevel | int? | null | The heading level (1 to 6) of the title, so it fits the outline of the page while its look stays the same. Defaults to 3. |
| HideHomeButton | bool | false | Prevents rendering the Home button of the default error UI. |
| HideIcon | bool | false | Prevents rendering the icon of the default error UI. |
| HideRecoverButton | bool | false | Prevents rendering the Recover button of the default error UI. |
| HideRefreshButton | bool | false | Prevents rendering the Refresh button of the default error UI. |
| HomeText | string? | null | The text of the Home button. Defaults to "Home". |
| HomeUrl | string? | null | The url of the home page for the Home button. Defaults to the site root. |
| HtmlAttributes | Dictionary<string, object>? | null | The HTML attributes to be applied to the root element of the boundary's error UI. |
| Icon | BitIconInfo? | null | The icon to display using custom CSS classes for external icon libraries. Takes precedence over IconName when both are set. |
| IconName | string? | null | The name of the icon to render in place of the built-in illustration. |
| IconTemplate | RenderFragment? | null | The template of the icon, replacing both the built-in illustration and IconName. |
| Id | string? | null | The id of the root element of the boundary's error UI. |
| MaximumErrorCount | int | 100 | The number of errors this boundary handles before it stops absorbing them and lets the next one through as fatal. Recovering resets the count. |
| Message | string? | null | The message rendered under the title of the default error UI. Nothing is rendered while it has no value. |
| NoLogging | bool | false | Prevents the boundary from logging the caught exception through the app's IErrorBoundaryLogger. |
| OnError | EventCallback<Exception> | The callback for when an error gets caught by the boundary, called before the error UI is rendered. | |
| OnRecover | EventCallback<BitErrorBoundaryRecoverReason> | The callback for when the boundary leaves its errored state, receiving which of the routes back out of it was taken. | |
| RecoverKeys | IEnumerable<object?>? | null | The values that recover the boundary as they change. |
| RecoverOnNavigation | bool | false | Recovers the boundary when the reader navigates to another location. |
| RecoverText | string? | null | The text of the Recover button. Defaults to "Recover". |
| RefreshText | string? | null | The text of the Refresh button. Defaults to "Refresh". |
| ShowCopyButton | bool | false | Renders a Copy button in the footer of the default error UI, putting the exception's full text on the clipboard. |
| ShowException | bool | false | Renders the full text of the caught exception, stack trace included, in a scrolling block that can receive the keyboard focus. |
| Style | string? | null | The CSS style of the root element of the boundary's error UI. |
| Styles | BitErrorBoundaryClassStyles? | null | Custom CSS styles for different parts of the boundary's default error UI. |
| Title | string? | null | The title of the default error UI. Defaults to "Oops, Something went wrong...", and an empty value drops the heading. |
BitErrorBoundary public members
| Name | Type | Default value | Description |
|---|---|---|---|
| CaughtException | Exception? | null | The exception the boundary is currently showing, or null while it has caught nothing. |
| Capture | void Capture(Exception exception) | Hands the boundary an exception that never passed through the renderer, putting it into exactly the state a caught one would. Call it on the renderer's synchronization context. | |
| CaptureAsync | Task CaptureAsync(Exception exception) | Capture from a thread that is not the renderer's. | |
| Recover | void Recover() | Clears the error and renders the boundary's content again, raising OnRecover. Never call it from rendering logic. | |
| Refresh | void Refresh() | Reloads the current page in the browser, which is what the default UI's Refresh button does. | |
| GoHome | void GoHome() | Navigates to HomeUrl, which is what the default UI's Home button does. |
BitComponentBase parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| AriaLabel | string? | null | Gets or sets the accessible label for the component, used by assistive technologies. |
| Class | string? | null | Gets or sets the CSS class name(s) to apply to the rendered element. |
| Dir | BitDir? | null | Gets or sets the text directionality for the component's content. |
| Disabled | bool | false | Gets or sets a value indicating whether the component is disabled and cannot respond to user interaction. |
| ForceAnimation | bool | false | Gets or sets a value indicating whether the component's animations play at their full duration even when reduced motion is requested. |
| HtmlAttributes | Dictionary<string, object> | new Dictionary<string, object>() | Captures additional HTML attributes to be applied to the rendered element, in addition to the component's parameters. An attribute written on the component wins over an entry of the same name. |
| Id | string? | null | Gets or sets the unique identifier for the component's root element. |
| Style | string? | null | Gets or sets the CSS style string to apply to the rendered element. |
| TabIndex | string? | null | Gets or sets the tab order index for the component when navigating with the keyboard. |
| Visibility | BitVisibility | BitVisibility.Visible | Gets or sets the visibility state (visible, hidden, or collapsed) of the component. |
BitComponentBase public members
| Name | Type | Default value | Description |
|---|---|---|---|
| UniqueId | Guid | Guid.NewGuid() | Gets the readonly unique identifier for the component's root element, assigned when the component instance is constructed. |
| RootElement | ElementReference | Gets the reference to the root HTML element associated with this component. |
BitErrorBoundaryClassStyles properties
Nothing here reaches the boundary's own content: while no error has been caught the boundary renders its children and no element of its own.
| Name | Type | Default value | Description |
|---|---|---|---|
| Root | string? | null | Custom CSS classes/styles for the root element of the BitErrorBoundary's error UI. |
| Header | string? | null | Custom CSS classes/styles for the header of the BitErrorBoundary, holding the icon, the title and the message, which is the part announced as the error appears. |
| Icon | string? | null | Custom CSS classes/styles for the icon of the BitErrorBoundary. |
| Title | string? | null | Custom CSS classes/styles for the title of the BitErrorBoundary. |
| Message | string? | null | Custom CSS classes/styles for the message of the BitErrorBoundary. |
| Exception | string? | null | Custom CSS classes/styles for the exception details block of the BitErrorBoundary. |
| Footer | string? | null | Custom CSS classes/styles for the footer of the BitErrorBoundary, which holds a replaced Footer exactly as it holds the default buttons. |
| RefreshButton | BitButtonClassStyles? | null | Custom CSS classes/styles for the Refresh button of the BitErrorBoundary. |
| HomeButton | BitButtonClassStyles? | null | Custom CSS classes/styles for the Home button of the BitErrorBoundary. |
| RecoverButton | BitButtonClassStyles? | null | Custom CSS classes/styles for the Recover button of the BitErrorBoundary. |
| CopyButton | BitButtonClassStyles? | null | Custom CSS classes/styles for the Copy button of the BitErrorBoundary. |
BitErrorBoundaryContext properties
What an ErrorTemplate is handed: the exception that was caught and the three ways out of it that the boundary's own error UI offers.
| Name | Type | Default value | Description |
|---|---|---|---|
| Exception | Exception | The exception the boundary caught. | |
| Recover | Action | Clears the error and renders the boundary's content again, exactly like the default UI's Recover button. | |
| Refresh | Action | Reloads the current page in the browser, exactly like the default UI's Refresh button. | |
| GoHome | Action | Navigates to HomeUrl, exactly like the default UI's Home button. |
BitErrorBoundaryRecoverReason enum
| Name | Value | Description |
|---|---|---|
| Manual | 0 | The Recover button of the default error UI, the Recover action of an ErrorTemplate's context, or a call to the Recover method. |
| Keys | 1 | One of the values of RecoverKeys differed from what the boundary last saw. |
| Navigation | 2 | The reader navigated to another location while RecoverOnNavigation was set. |
BitVisibility enum
| Name | Value | Description |
|---|---|---|
| Visible | 0 | The content of the component is visible. |
| Hidden | 1 | The content of the component is hidden, but the space it takes on the page remains (visibility:hidden). |
| Collapsed | 2 | The component is hidden (display:none). |
BitDir enum
| Name | Value | Description |
|---|---|---|
| Ltr | 0 | Ltr (left to right) is to be used for languages that are written from the left to the right (like English). |
| Rtl | 1 | Rtl (right to left) is to be used for languages that are written from the right to the left (like Arabic). |
| Auto | 2 | Auto lets the user agent decide. It uses a basic algorithm as it parses the characters inside the element until it finds a character with a strong directionality, then applies that directionality to the whole element. |
Feedback
Found a mistake, a gap, or something that could be clearer? Every page and every component is one click from its source.