Extras
MessageBox
Bit.BlazorUI.Extras
BitMessageBox is a pre-implemented box for showing a message with a title, a body, an optional severity icon and the set of buttons it is answered with (Ok, Ok/Cancel, Yes/No, Yes/No/Cancel, or none at all). It renders inline, inside a BitModal, or - the usual way - through the BitMessageBoxService, which shows it in a modal and hands back the BitMessageBoxResult it was answered with. Every part of it takes a template, the answer can be guarded before it is handed over, and the whole box scales with its size.
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.
Usage
Every example is live. Open its code to see exactly what produced the component running underneath.
Basic
The basic usage of the BitMessageBox: a Title, a Body and the Ok button that answers it.
The body keeps the line breaks written into it and wraps the lines that are too long for the box,
and OkText renames the button.
It's a title
It's a body.
Buttons
Buttons picks the set the message box is answered with, and OnResult reports which
button ended it as a BitMessageBoxResult - the close button answering with None, so a
message box that was walked away from is told apart from one that was refused. CancelText,
YesText and NoText rename the other buttons the way OkText renames the Ok one.
None is the set for a message box that only tells the reader something: it leaves the footer
off entirely, so the box is dismissed through its close button (or, in a modal, the Escape key and
the overlay) rather than answered.
Ok
A single button, which is the default.
OkCancel
An Ok and a Cancel button.
YesNo
A Yes and a No button.
YesNoCancel
A Yes, a No and a Cancel button.
None
No buttons at all - only the close button ends this one.
Last answer: None
Order, focus & emphasis
Reversed renders the action buttons the other way round, which also reverses the order the
keyboard reaches them in, and DefaultButton names the one AutoFocus puts the focus on -
point it at Cancel or No for the message boxes that ask about something destructive, so the answer a
stray keystroke gives is the harmless one, and at None to land the focus on the close button
instead, which is also where it goes for a message box that renders no action buttons of its own.
The affirmative button always keeps the filled look;
PrimaryButtonColor is what paints it - a red Delete beside a neutral Keep - and
ButtonColor repaints the whole set. The size of the message box scales the buttons with it.
Reversed
Cancel comes first here.
Default button
No is the button the focus would land on.
Delete the file?
The destructive action is the one that stands out.
Icon
A message box carries a leading glyph as soon as it is given one: IconName for the built-in
Fluent set, Icon for an external icon library, or IconTemplate for markup of your own.
A Color brings a glyph with it too (see the Color section), and HideIcon takes it back
off. The glyph is decoration by default; IconAriaLabel is what turns it into an image that is
announced, for the message boxes whose severity is carried by the icon alone.
IconName
A glyph from the built-in Fluent set.
IconTemplate
Any markup can stand in for the glyph.
Close button
The close button in the header dismisses the message box without an answer:
it raises OnClose and reports BitMessageBoxResult.None. ShowCloseButton takes it
away for a message box that has to be answered, CloseIconName (or CloseIcon) changes its
glyph, and CloseButtonTitle is both its tooltip and its accessible name - which is what to
translate, since an icon-only button has no words of its own.
No close button
This one has to be answered.
Custom close button
Another glyph, and another name for it.
Templates
Each of the three parts takes markup instead of text: BodyTemplate (or the child content)
for a body that is more than a paragraph, HeaderTemplate for a header of your own - which
takes the icon, the title and the close button with it - and FooterTemplate for actions the
built-in sets do not cover. The controls in a footer of your own are the page's own, so nothing in
them answers the message box by itself: AnswerAsync is what ends it with the answer of your
choosing, down the same road a pressed button takes.
Delete the workspace?
Everything in Design system is removed, including:
- 18 projects
- 4 shared libraries
Last answer: None
BitModal
Show the BitMessageBox inside a BitModal component and close it using the OnClose event, which every
button of the message box raises after its own callback. AutoFocus moves the focus onto the
default button once the box is on the screen, which is what a dialog that takes over the screen has
to do for the keyboard and the screen reader.
BitModalService
Show the BitMessageBox as the content of a modal shown by the BitModalService. The message box answers
the modal through OnResult, so awaiting the modal reference is awaiting the answer.
Last answer: None
BitMessageBoxService
The BitMessageBoxService does all of that in a single call: it shows the message box in a modal, moves
the focus into it, names the dialog after the title and describes it with the body, and hands back the
BitMessageBoxResult once the box is closed. ShowInfo, ShowSuccess,
ShowWarning, ShowSevereWarning and ShowError are the same call with a severity
already set - the three urgent ones are announced as alerts. The service shows through the
BitModalService, so a BitModalContainer has to be mounted in the layout for anything to render.
Confirmation
Confirm asks a question and reports whether it was answered affirmatively: only Ok and Yes
answer true, so a refusal, a dismissal and a message box that never rendered all leave the
destructive branch untaken. BitMessageBoxParameters is the way to say the rest -
the buttons, the severity, the wording, the default button, and through its Modal member,
anything about the modal the box is shown in.
Last answer:
Guarding the answer
OnBeforeResult is asked before the message box hands over an answer, and setting
Cancel on its arguments refuses it: nothing is reported, nothing is closed, and a box shown
through the service stays open with its caller still waiting. It guards every button the message box
draws, the close button included - the Escape key and the overlay belong to the layer around it,
which BitModalParameters.CanClose guards instead. AutoLoading keeps the pressed button
spinning for as long as the guard and the callbacks of the answer run, which is what stops a slow
answer from being handed in twice; only one answer is taken per press either way.
Delete the file?
Last answer: None
Color
Color is the severity of the message: it paints the leading glyph and, for the five severities
that have one, picks the glyph itself - Info, Success (Completed), Warning, SevereWarning and Error.
Setting a color is therefore all it takes to give a message box its icon, and IconName still
overrides which glyph that is.
Info
Something worth knowing.
Success
Something went well.
Warning
Something needs attention.
SevereWarning
Something needs attention now.
Error
Something went wrong.
Primary
The accent of the theme.
External Icons
Besides the built-in Fluent set exposed through IconName and CloseIconName, the
Icon and CloseIcon parameters render icons from any CSS-class based library such as
FontAwesome or Bootstrap Icons. Pass the raw classes directly, or use the BitIconInfo helpers
(
Css, Fa and Bi). When both are set, Icon wins.
Remember to reference the icon library's stylesheet in your app.
FontAwesome
The glyph comes from FontAwesome through BitIconInfo.Fa.
Bootstrap Icons
The glyph and the close icon come from Bootstrap Icons.
Size
Size scales the inset of the message box, its title, its body text and its leading glyph
together, so a small message box is not left carrying a medium-sized title or icon. The default is
the medium one.
Small
The small size.
Medium
The medium size.
Large
The large size.
Style & Class
Customize the appearance of BitMessageBox using styles and CSS classes. Style and Class
reach the root element, while Styles and Classes reach every part of it by name -
including each action button, with ActionButton standing in for the ones given nothing of
their own.
It's a title
It's a body.
It's a title
It's a body.
RTL
Use BitMessageBox in right-to-left (RTL).
عنوان پیام
متن تست پیام...
API
Every parameter, public member, sub-class and enum this component exposes.
BitMessageBox parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| AutoFocus | bool | false | Moves the focus onto the default action button once the message box is rendered, and marks it with the autofocus attribute the surrounding layer reads, so a message box kept mounted between showings lands the focus on it on every opening. The BitMessageBoxService defaults it to true for the message boxes it shows. |
| AutoLoading | bool | false | Enables the loading state of the action button that was pressed for as long as its callback runs. |
| Body | string? | null | The body of the message box. Line breaks in it are kept and long lines wrap. |
| BodyTemplate | RenderFragment? | null | The template of the body of the message box, which takes the place of Body. |
| Buttons | BitMessageBoxButtons | BitMessageBoxButtons.Ok | The set of buttons the message box renders in its footer. |
| ButtonColor | BitColor? | null | The color of the action buttons of the message box. Tertiary by default. |
| CancelText | string? | null | The text of the Cancel button. |
| ChildContent | RenderFragment? | null | The alias of BodyTemplate. |
| Classes | BitMessageBoxClassStyles? | null | Custom CSS classes for different parts of the message box. |
| CloseButtonTitle | string? | null | The title (and aria-label) of the close button, for accessibility and localization. Defaults to "Close". |
| CloseIcon | BitIconInfo? | null | The icon of the close button, provided as custom CSS classes of an external icon library. |
| CloseIconName | string? | null | The name of the icon of the close button, from the built-in Fluent UI icons. |
| Color | BitColor? | null | The general color of the message box, which paints its leading icon and - unless IconName says otherwise - picks the glyph. |
| DefaultButton | BitMessageBoxResult? | null | The action button that AutoFocus moves the focus onto, or None for the close button. Defaults to the affirmative button of the set (Ok, or Yes), and to the close button for a message box that renders no action buttons. |
| FooterTemplate | RenderFragment? | null | The template used to render the footer of the message box, which takes the place of its action buttons. The controls in it are the page's own, so AnswerAsync is what ends the message box with an answer. |
| HeaderTemplate | RenderFragment? | null | The template used to render the header of the message box, which takes the place of its icon, title and close button. |
| HideIcon | bool | false | Removes the leading icon of the message box, which a Color would otherwise bring with it. |
| Icon | BitIconInfo? | null | The leading icon of the message box, provided as custom CSS classes of an external icon library. |
| IconAriaLabel | string? | null | The accessible name of the leading icon, which turns it from decoration into an image that is announced. |
| IconName | string? | null | The name of the leading icon of the message box, from the built-in Fluent UI icons. If unset, the icon is selected automatically based on Color. |
| IconTemplate | RenderFragment? | null | The template used to render the leading icon of the message box. |
| NoText | string? | null | The text of the No button. |
| OkText | string? | null | The text of the Ok button. |
| OnBeforeResult | EventCallback<BitMessageBoxBeforeResultArgs> | The event callback asked before the message box hands over an answer. Setting Cancel on its arguments refuses the answer and keeps the message box open. It guards every button the message box draws, the close button included. | |
| OnCancel | EventCallback | The event callback for the Cancel button of the message box. | |
| OnClose | EventCallback | The event callback for closing the message box, raised by every button it renders of its own - after the callback of that button and after OnResult. | |
| OnNo | EventCallback | The event callback for the No button of the message box. | |
| OnOk | EventCallback | The event callback for the Ok button of the message box. | |
| OnResult | EventCallback<BitMessageBoxResult> | The event callback for the answer the message box was given. The close button answers with None, the others with the result they stand for. | |
| OnYes | EventCallback | The event callback for the Yes button of the message box. | |
| PrimaryButtonColor | BitColor? | null | The color of the affirmative action button (Ok, or Yes), which falls back to ButtonColor where it is not set. |
| Reversed | bool | false | Renders the action buttons in the reverse order, which also reverses the order the keyboard reaches them in. |
| ShowCloseButton | bool | true | Renders the close button in the header of the message box. |
| Size | BitSize? | null | The size of the message box, which scales its inset, its title, its body text and its leading icon together. |
| Styles | BitMessageBoxClassStyles? | null | Custom CSS styles for different parts of the message box. |
| Title | string? | null | The title of the message box. |
| YesText | string? | null | The text of the Yes button. |
BitMessageBox public members
| Name | Type | Default value | Description |
|---|---|---|---|
| AnswerAsync | Task | Answers the message box as though the button standing for that result had been pressed, down the same road: the guard is asked first, then the callback of that answer, OnResult and OnClose. This is how a footer of your own ends the message box with a real answer. | |
| Result | BitMessageBoxResult | BitMessageBoxResult.None | The answer the last showing of this message box was given, or None while it has not been answered. |
| FocusAsync | ValueTask | Moves the focus onto the default action button of the message box, or onto its close button where it renders no action buttons of its own. |
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. |
| 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. |
| Id | string? | null | Gets or sets the unique identifier for the component's root element. |
| IsEnabled | bool | true | Gets or sets a value indicating whether the component is enabled and can respond to user interaction. |
| 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. |
BitMessageBoxClassStyles properties
| Name | Type | Default value | Description |
|---|---|---|---|
| Root | string? | null | Custom CSS classes/styles for the root element of the BitMessageBox. |
| Container | string? | null | Custom CSS classes/styles for the container of the BitMessageBox. |
| Header | string? | null | Custom CSS classes/styles for the header of the BitMessageBox. |
| IconContainer | string? | null | Custom CSS classes/styles for the icon container of the BitMessageBox. |
| Icon | string? | null | Custom CSS classes/styles for the icon of the BitMessageBox. |
| Title | string? | null | Custom CSS classes/styles for the title of the BitMessageBox. |
| Spacer | string? | null | Custom CSS classes/styles for the BitSpacer of the BitMessageBox. |
| CloseButton | BitButtonClassStyles? | null | Custom CSS classes/styles for the CloseButton of the BitMessageBox. |
| Body | string? | null | Custom CSS classes/styles for the body of the BitMessageBox. |
| Footer | string? | null | Custom CSS classes/styles for the footer of the BitMessageBox. |
| ActionButton | BitButtonClassStyles? | null | Custom CSS classes/styles for every action button of the BitMessageBox that was given none of its own. |
| OkButton | BitButtonClassStyles? | null | Custom CSS classes/styles for the OkButton of the BitMessageBox. |
| CancelButton | BitButtonClassStyles? | null | Custom CSS classes/styles for the CancelButton of the BitMessageBox. |
| YesButton | BitButtonClassStyles? | null | Custom CSS classes/styles for the YesButton of the BitMessageBox. |
| NoButton | BitButtonClassStyles? | null | Custom CSS classes/styles for the NoButton of the BitMessageBox. |
BitMessageBoxBeforeResultArgs properties
The arguments of the OnBeforeResult callback, which is asked before a message box hands over the answer a button of its own was pressed for.
| Name | Type | Default value | Description |
|---|---|---|---|
| Result | BitMessageBoxResult | BitMessageBoxResult.None | The answer that is about to be handed over: the result of the button that was pressed, or None for the close button. Read-only - Cancel is the guard's say over it. |
| Cancel | bool | false | Set to true to keep the message box open and hand over no answer. |
BitMessageBoxParameters properties
The set of parameters a message box shown through the BitMessageBoxService is customized with. Every member is nullable and null means "not set", so the BitMessageBox default stands.
| Name | Type | Default value | Description |
|---|---|---|---|
| AutoFocus | bool? | null | Moves the focus onto the default action button. Defaults to true for a message box shown through the service. |
| AutoLoading | bool? | null | Enables the loading state of the action button that was pressed for as long as its callback runs. |
| Body | string? | null | The body of the message box, which is also what describes the dialog it is shown in. |
| BodyTemplate | RenderFragment? | null | The template of the body of the message box. |
| Buttons | BitMessageBoxButtons? | null | The set of buttons the message box renders in its footer. |
| ButtonColor | BitColor? | null | The color of the action buttons of the message box. |
| CancelText | string? | null | The text of the Cancel button. |
| Classes | BitMessageBoxClassStyles? | null | Custom CSS classes for different parts of the message box. |
| CloseButtonTitle | string? | null | The title (and aria-label) of the close button. |
| CloseIcon | BitIconInfo? | null | The icon of the close button, provided as custom CSS classes of an external icon library. |
| CloseIconName | string? | null | The name of the icon of the close button, from the built-in Fluent UI icons. |
| Color | BitColor? | null | The general color of the message box, which is the severity of its message. Warning, SevereWarning and Error are announced as alerts. |
| DefaultButton | BitMessageBoxResult? | null | The action button the focus is moved onto, or None for the close button. |
| Dir | BitDir? | null | The general directionality of the message box and of the modal it is shown in. |
| FooterTemplate | RenderFragment? | null | The template used to render the footer of the message box. |
| HeaderTemplate | RenderFragment? | null | The template used to render the header of the message box. |
| HideIcon | bool? | null | Removes the leading icon of the message box. |
| Icon | BitIconInfo? | null | The leading icon of the message box, provided as custom CSS classes of an external icon library. |
| IconAriaLabel | string? | null | The accessible name of the leading icon. |
| IconName | string? | null | The name of the leading icon of the message box, from the built-in Fluent UI icons. |
| IconTemplate | RenderFragment? | null | The template used to render the leading icon of the message box. |
| Id | string? | null | The id of the rendered message box. The service generates one when none is given, since the ids of the title and the body are derived from it. |
| Modal | BitModalParameters? | null | The parameters of the BitModal the message box is shown in. What is set here wins over the values the service works out on its own. |
| NoText | string? | null | The text of the No button. |
| OkText | string? | null | The text of the Ok button. |
| OnBeforeResult | EventCallback<BitMessageBoxBeforeResultArgs> | The event callback asked before the message box hands over an answer. Setting Cancel on its arguments keeps the message box open and leaves the caller of the service still waiting. | |
| Persistent | bool? | null | Keeps the message box alive through the lifecycle of the application until it is closed, rather than only for as long as the modal container that renders it. |
| PrimaryButtonColor | BitColor? | null | The color of the affirmative action button (Ok, or Yes), which falls back to ButtonColor. |
| Reversed | bool? | null | Renders the action buttons in the reverse order. |
| ShowCloseButton | bool? | null | Renders the close button in the header of the message box. |
| Size | BitSize? | null | The size of the message box. |
| Styles | BitMessageBoxClassStyles? | null | Custom CSS styles for different parts of the message box. |
| Title | string? | null | The title of the message box, which is also what names the dialog it is shown in. |
| YesText | string? | null | The text of the Yes button. |
BitMessageBoxResult enum
| Name | Value | Description |
|---|---|---|
| None | 0 | The message box was dismissed rather than answered: its close button, or - for one shown through the service - the Escape key, a click on the overlay, or the page closing the modal itself. |
| Ok | 1 | The Ok button ended the showing. |
| Cancel | 2 | The Cancel button ended the showing. |
| Yes | 3 | The Yes button ended the showing. |
| No | 4 | The No button ended the showing. |
BitSize enum
| Name | Value | Description |
|---|---|---|
| Small | 0 | The small size. |
| Medium | 1 | The medium size. |
| Large | 2 | The large size. |
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.