Skip to content

Extras

MessageBox

Bit.BlazorUI.ExtrasConfirmAlertMsgBox

BitMessageBox is a ready-made box for a message with a title, a body, an optional severity icon and the buttons it is answered with (Ok, Ok/Cancel, Yes/No, Yes/No/Cancel or none). Render it inline, inside a BitModal, or through the BitMessageBoxService, which shows it in a modal and returns the BitMessageBoxResult it was answered with.

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

A Title, a Body and the Ok button. Line breaks in the body are kept and long lines wrap.

It's a title
It's a body.

Buttons

Buttons picks the set; OnResult reports which button answered (the close button answers None). OkText, CancelText, YesText and NoText rename them, and the None set leaves the footer off.

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 flips the buttons (and their tab order). DefaultButton is where AutoFocus lands - point it at the harmless answer of a destructive question, or at None for the close button. PrimaryButtonColor paints the affirmative button, ButtonColor the whole set.

Reversed
Cancel comes first here.
Delete the file?
Keep is where the focus would land.
ButtonColor
Every button in the primary color.

Icon

IconName (built-in), Icon (external, see External Icons) or IconTemplate (any markup) adds a leading glyph (a Color brings one too, see Color). The glyph is decorative unless IconAriaLabel names it - do that when the icon alone carries the severity.

IconName
A glyph from the built-in Fluent set.
IconTemplate
Any markup can stand in for the glyph.
IconAriaLabel
The glyph is announced as "Warning".

Close button

The close button dismisses without an answer (OnClose, result None). ShowCloseButton removes it, CloseIconName / CloseIcon change its glyph, and CloseButtonTitle is its tooltip and accessible name - the text to localize.

No close button
This one has to be answered.
Custom close button
Another glyph, and another name for it.

Templates

BodyTemplate (or child content), HeaderTemplate (replaces icon, title and close button) and FooterTemplate (replaces the buttons) take markup. Controls in a custom footer answer through AnswerAsync, which takes the same path as a pressed button.

Delete the workspace?
Everything in Design system is removed, including:
  • 18 projects
  • 4 shared libraries
Read what this means

Last answer: None

Guarding the answer

Set Cancel in OnBeforeResult to refuse an answer: nothing is reported and the box stays open. It guards every button of the box, the close button included (a modal's Escape and overlay are guarded by BitModalParameters.CanClose). AutoLoading spins the pressed button while it runs, and the close button takes the answer back meanwhile, cancelling the args' CancellationToken.

Delete the file?

Last answer: None

BitModal

Inside a BitModal, close it from OnClose and turn AutoFocus on. Give the box an Id and point the modal's TitleAriaId / SubtitleAriaId at {Id}-ttl / {Id}-bdy so the dialog is named and described; TitleElement sets the heading level.

BitModalService

As the content of a BitModalService modal: OnResult closes the modal with the answer, so awaiting the modal reference awaits the answer.



Last answer: None

BitMessageBoxService

One call shows the box in a modal, focuses it, names and describes the dialog, and returns the BitMessageBoxResult. ShowInfo ... ShowError preset the severity. Questions and the Warning, SevereWarning and Error severities are alertdialogs. A CancellationToken closes the box from code (answer None). Needs a BitModalContainer in the layout. A FooterTemplate of a service box answers through AnswerAsync too: a component of your own in it gets the box as a [CascadingParameter] BitMessageBox.


Last answer: None

Confirmation

Confirm returns true only for Ok or Yes - a refusal or a dismissal is false. BitMessageBoxParameters sets everything else, including the modal through its Modal member (the second one is Blocking: a click beside it does not dismiss it).


Last answer: -

Prompt

Prompt asks for text and returns it, or null when dismissed. The field takes the focus and Enter answers (Ctrl+Enter when Multiline). Required, Validator and AsyncValidator (a server check, run on answering while the field shows it is busy, and given up on by Cancel) refuse a value with a message under the field; Label, Description, Placeholder, InputType, AutoComplete and MaxLength shape it. Try naming the new folder "Projects".


Last answer: null

Cascading parameters

BitParams with a BitMessageBoxParams sets defaults - button texts, colors, order, size - for every message box under it; a box's own value wins (the second keeps its own Yes text). Wrap the BitModalContainer to reach the service's boxes too. Title, body, buttons and color are not cascaded.

Save changes?
Your edits have not been saved.
Discard the draft?
The draft is removed for good.

Color

Color is the severity: it paints the glyph and, for Info, Success, Warning, SevereWarning and Error, picks it. IconName still overrides the glyph and HideIcon removes it.

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.
HideIcon
An Error without its glyph.

External Icons

Icon and CloseIcon take any CSS-class icon library (raw classes or BitIconInfo.Css / Fa / Bi) and win over IconName / CloseIconName. Reference the library's stylesheet in your app.

FontAwesome
The glyph comes from FontAwesome.
Bootstrap Icons
The glyph and the close icon come from Bootstrap Icons.

Size

Size scales the inset, title, body, glyph and buttons together. Medium is the default.

Small
The small size.
Medium
The medium size.
Large
The large size.

Style & Class

Style / Class reach the root, Styles / Classes each part (ActionButton covers the buttons given nothing of their own). The public --bit-MessageBox-* variables (see the CSS variables table) re-skin it from :root, an ancestor or Style. They restyle the default, not a choice: an explicit Color or Size wins over them for what it sets.

It's a title
It's a body.
It's a title
It's a body.
CSS variables
Centered, with a larger glyph.

RTL

Use BitMessageBox 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.

BitMessageBox CSS variables

Name Default value Description
--bit-MessageBox-padding var(--bit-spa-dialog) Inset of the message box. The Size parameter wins over it.
--bit-MessageBox-gap spacing(2) Room between the header, the body and the footer.
--bit-MessageBox-min-width spacing(40) Width the message box does not shrink below (never past the max width, unset on small screens). The Size parameter wins over it.
--bit-MessageBox-max-width var(--bit-siz-dialog-max-width) in a modal, 100% inline Width the message box stops growing at: the theme's dialog width where it is the content of a modal, its container's width where it is rendered inline.
--bit-MessageBox-max-height the screen height a modal leaves Height past which the body scrolls (header and footer stay put).
--bit-MessageBox-text-align var(--bit-layout-dialog-text-align) Alignment of the title and the body.
--bit-MessageBox-icon-color the text color Color of the leading icon. The Color parameter wins over it.
--bit-MessageBox-icon-size var(--bit-siz-icon-md) Size of the leading icon. The Size parameter wins over it.
--bit-MessageBox-title-color var(--bit-clr-fg-pri) Color of the title.
--bit-MessageBox-title-font-size var(--bit-tpg-dialog-title-font-size) Size of the title. The Size parameter wins over it.
--bit-MessageBox-title-font-weight var(--bit-tpg-dialog-title-font-weight) Weight of the title.
--bit-MessageBox-body-color var(--bit-clr-fg-sec) Color of the body.
--bit-MessageBox-body-font-size var(--bit-tpg-fs-md) Size of the body. The Size parameter wins over it.
--bit-MessageBox-actions-gap spacing(2) Room between the action buttons.
--bit-MessageBox-actions-justify var(--bit-layout-dialog-actions-justify) How the action buttons sit along the footer.

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 (see DefaultButton) once the message box is rendered, and on every opening of a modal it stays mounted in. The BitMessageBoxService turns it on for the 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. Its id is {Id}-bdy, for the aria-describedby of a modal around it.
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. An explicit value wins over --bit-MessageBox-icon-color; left unset, the icon takes the text color unless that variable says otherwise.
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; the box is cascaded, so a component of your own in it can take it as a [CascadingParameter] BitMessageBox.
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. An explicit value wins over the --bit-MessageBox-* size variables; left unset, the message box is medium unless they say otherwise.
Styles BitMessageBoxClassStyles? null Custom CSS styles for different parts of the message box.
Title string? null The title of the message box. Its id is {Id}-ttl, for the aria-labelledby of a modal around it.
TitleElement string? null The HTML element the title is rendered as (h5 by default). Pick the heading level that fits the page outline - h2 is usual for a dialog; the look does not change.
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.
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.

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.
CancellationToken CancellationToken Cancelled when the close or the Cancel button takes the answer back while the guard is still working it out. Hand it to the guard's slow work; an answer taken back is never handed over.

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. An explicit value wins over --bit-MessageBox-icon-color.
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. A component of your own in it takes the box as a [CascadingParameter] BitMessageBox and answers the showing with its AnswerAsync.
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. An explicit value wins over the --bit-MessageBox-* size variables.
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.
TitleElement string? null The HTML element the title is rendered as (h5 by default).
YesText string? null The text of the Yes button.

BitMessageBoxPromptParameters properties

The parameters of BitMessageBoxService.Prompt: everything BitMessageBoxParameters sets, plus the text field the answer is typed into.

Name Type Default value Description
AsyncValidator Func<string, CancellationToken, Task<string?>>? null An asynchronous check (a server call) run on answering, after Required and Validator accept the value: return an error message to refuse it, or null to accept it. The field shows it is busy meanwhile, and an edit takes its message away. The token is cancelled when the check is given up on (Cancel, the close button, Escape, the token of the showing); an exception it throws closes the box and is rethrown out of Prompt.
AutoComplete string? null The autocomplete attribute of the text field, such as off, username or current-password.
CanRevealPassword bool? null Adds a button to a Password field that shows what was typed.
Description string? null The help text under the text field, which also describes it.
InputType BitInputType? null The type of the text field, such as Password or Email. Text by default.
Label string? null The visible label of the text field. Without one the question in the body names the field.
MaxLength int? null The maximum number of characters the text field accepts.
Multiline bool? null Renders a multi-line text field, where Enter starts a new line and Ctrl+Enter answers the box.
Placeholder string? null The placeholder of the text field.
Required bool? null Refuses an empty or white-space answer, showing RequiredMessage under the field.
RequiredMessage string? null The error message a Required field shows when it is left empty. "A value is required." by default.
Validator Func<string, string?>? null Checks the answer before it is accepted: return an error message to refuse it (shown under the field), or null to accept it. Re-runs on every edit once a value has been refused. An empty field is checked as an empty string, never null.
Value string? null The initial value of the text field, selected when the box opens.

BitMessageBoxButtons enum

Name Value Description
Ok 0 A single Ok button, which answers with BitMessageBoxResult.Ok.
OkCancel 1 An Ok and a Cancel button.
YesNo 2 A Yes and a No button.
YesNoCancel 3 A Yes, a No and a Cancel button.
None 4 No action buttons at all, which leaves the footer off the message box entirely: it is dismissed rather than answered, so it answers with BitMessageBoxResult.None.

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.

BitColor enum

Name Value Description
Primary 0 Primary general color.
Secondary 1 Secondary general color.
Tertiary 2 Tertiary general color.
Info 3 Info general color.
Success 4 Success general color.
Warning 5 Warning general color.
SevereWarning 6 SevereWarning general color.
Error 7 Error general color.
PrimaryBackground 8 Primary background color.
SecondaryBackground 9 Secondary background color.
TertiaryBackground 10 Tertiary background color.
PrimaryForeground 11 Primary foreground color.
SecondaryForeground 12 Secondary foreground color.
TertiaryForeground 13 Tertiary foreground color.
PrimaryBorder 14 Primary border color.
SecondaryBorder 15 Secondary border color.
TertiaryBorder 16 Tertiary border color.

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.