Skip to content
# Dialog ## Description A modal pop-up that puts a short decision in front of the page and waits for an answer. It comes with a title, a message and an Ok/Cancel pair out of the box, takes the focus and holds it while it is open, closes on Escape or on a click outside, and hands back both which button ended it and which gesture did - either through a two-way bound IsOpen or through an awaitable Show() call. ## Parameters | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | AbsolutePosition | `bool` | false | When true, the Dialog will be positioned absolute instead of fixed, so it covers its nearest positioned ancestor instead of the screen. | | AutoFocus | `bool` | true | Moves the focus into the Dialog when it opens, onto the first focusable element it holds, falling back to the Dialog itself when it holds none. | | AutoFocusButton | `BitDialogButton?` | null | Which of the Dialog's own buttons AutoFocus lands on, instead of the first focusable element the Dialog holds. Takes precedence over AutoFocusSelector. | | AutoFocusSelector | `string?` | null | The CSS selector of the element inside the Dialog that AutoFocus lands on, instead of the first focusable element it holds. A selector that matches nothing visible falls back to that first element. | | AutoToggleScroll | `bool` | false | Enables the auto scrollbar toggle behavior of the Dialog, which stops the scroller from scrolling for as long as the Dialog is open. The scroller is the one ScrollerElement or ScrollerSelector names, the one a surrounding BitAppShell cascades when neither does, and the page when there is no shell either. | | Body | `RenderFragment?` | null | Alias for child content. | | CancelText | `string?` | Cancel | The text of the cancel button. | | ChildContent | `RenderFragment?` | null | The content of the Dialog, it can be any custom tag or text. | | Classes | `BitDialogClassStyles?` | null | Custom CSS classes for different parts of the BitDialog component. | | CloseButtonTitle | `string?` | null | The title (and aria-label) of the close button, for accessibility and localization. Defaults to "Close" when not set. | | CloseIcon | `BitIconInfo?` | null | Gets or sets the icon to display for the close button using custom CSS classes for external icon libraries. Takes precedence over CloseIconName when both are set. | | CloseIconName | `string?` | null | Gets or sets the name of the icon to display for the close button from the built-in Fluent UI icons. | | CloseOnEscape | `bool` | true | Dismisses the Dialog when the Escape key is pressed while the focus is inside it. A blocking Dialog ignores the Escape key whatever this is set to. | | Color | `BitColor?` | null | The general color of the Dialog, which its Ok and Cancel buttons, the Ok spinner and the focus ring of both are painted in. Defaults to Primary. | | DefaultIsOpen | `bool?` | null | The initial opening state of the Dialog in the uncontrolled mode, which is when the IsOpen parameter is not set. It is read once, at initialization, so closing such a Dialog is not undone by the next render. | | DragElementSelector | `string?` | null | The CSS selector of the element the Dialog is dragged by. By default it is the header when the Dialog has one, and the whole container when it has none. | | FooterTemplate | `RenderFragment?` | null | Used to customize how the footer inside the Dialog is rendered. | | FullHeight | `bool` | false | Makes the Dialog height 100% of the area it is positioned in. | | FullSize | `bool` | false | Makes the Dialog width and height 100% of the area it is positioned in. | | FullWidth | `bool` | false | Makes the Dialog width 100% of the area it is positioned in. | | HeaderTemplate | `RenderFragment?` | null | Used to customize the header of the Dialog, replacing the Title and Subtitle while keeping the close button beside it. | | Height | `string?` | null | The CSS height of the Dialog surface. A Dialog is as tall as its content by default, and FullHeight and FullSize take precedence over this. | | IsAlert | `bool?` | null | Determines the ARIA role of the Dialog (alertdialog/dialog). If this is set, it will override the ARIA role determined by IsBlocking and IsModeless. | | IsBlocking | `bool` | false | Prevents the Dialog from being dismissed by a click on the overlay or by the Escape key, leaving its buttons as the only way out. | | IsCancelButtonEnabled | `bool` | true | Whether the Cancel button of the Dialog can be pressed. Unlike IsEnabled, which turns the whole Dialog off, this leaves every other way out of the Dialog working. | | IsDraggable | `bool` | false | Whether the Dialog can be dragged around. | | IsModeless | `bool` | false | Whether the Dialog should be modeless (e.g. not dismiss when focusing/clicking outside of the Dialog). If true, IsBlocking is ignored, there will be no overlay, and the focus is not trapped - though the Dialog still takes it when it opens unless AutoFocus is turned off. | | IsOkButtonEnabled | `bool` | true | Whether the Ok button of the Dialog can be pressed. This is what holds the answer shut until the content of the Dialog provides it - a consent to tick, a name to type - without turning the rest of the Dialog off the way IsEnabled would. | | IsOpen | `bool` | false | Whether the Dialog is displayed. | | IsOpenChanged | `EventCallback<bool>` | null | A callback function for when the Dialog is opened or closed. | | KeepMounted | `bool` | false | Keeps the Dialog in the DOM while it is closed, hidden, instead of removing it - so its content, and whatever state it holds, survives until the next showing. Nothing is rendered until the first time it opens, so a Dialog that is never opened still costs nothing. | | MaxHeight | `string?` | null | The CSS maximum height of the Dialog surface. Defaults to 100% of the area the Dialog is positioned in, and setting it replaces that default rather than adding to it. | | MaxWidth | `string?` | null | The CSS maximum width of the Dialog surface. Defaults to the narrower of 100% of the area the Dialog is positioned in and the --bit-siz-dialog-max-width theme token, and setting it replaces that default rather than adding to it - min(100%, 32rem) is the whole of a responsive Dialog. | | Message | `string?` | null | The message to display in the dialog. It also describes the Dialog to a screen reader unless a Subtitle or a SubtitleAriaId takes that job instead. | | MinHeight | `string?` | null | The CSS minimum height of the Dialog surface. | | MinWidth | `string?` | null | The CSS minimum width of the Dialog surface, the floor under a Dialog whose message is a handful of words. | | NoDismissPreventedAnimation | `bool` | false | Turns off the shake the Dialog plays when a dismissal is refused. OnDismissPrevented is raised either way. | | OkText | `string?` | Ok | The text of the ok button. | | OnCancel | `EventCallback<MouseEventArgs>` | null | A callback function for when the Cancel button is clicked. | | OnClose | `EventCallback<MouseEventArgs>` | null | A callback function for when the Close button is clicked. | | OnDismiss | `EventCallback<MouseEventArgs>` | null | A callback function for when the the dialog is dismissed (closed). It is invoked for every closing the Dialog carries out itself, including a Close or Toggle call, and DismissReason names the gesture that ended the showing by the time it runs. | | OnDismissing | `EventCallback<BitDialogDismissArgs>` | null | A callback function invoked before the Dialog closes, letting the closing be refused. Set Cancel on the arguments to leave the Dialog where it is, and read Reason to tell the gestures apart. It is awaited, so it can run asynchronous work of its own. | | OnDismissPrevented | `EventCallback<BitDialogDismissReason>` | null | A callback function for when a dismissal was refused: the Escape key on a Dialog that does not take it, or a click on the overlay of a blocking one. The Dialog shakes on its own; this is for saying why. | | OnOverlayClick | `EventCallback<MouseEventArgs>` | null | A callback function for when the overlay of the Dialog is clicked, whether or not the click goes on to dismiss the Dialog. | | OnOk | `EventCallback<MouseEventArgs>` | null | A callback function for when the Ok button is clicked. The Dialog waits for it before closing and shows a spinner in place of the Ok text while it waits. | | OnOpen | `EventCallback` | null | A callback function for when the Dialog is opened. | | Position | `BitDialogPosition` | BitDialogPosition.Center | Position of the Dialog on the screen. | | RestoreFocus | `bool` | true | Hands the focus back to whatever held it when the Dialog opened, once the Dialog closes. | | ScrollerElement | `ElementReference?` | null | Set the element reference for which the Dialog disables its scroll if applicable. Takes precedence over ScrollerSelector when both are set. | | ScrollerSelector | `string?` | null | The CSS selector of the element whose scrolling the Dialog holds while it is open, for the layouts whose scroller is not the page itself. A Dialog inside a BitAppShell holds the shell's scroller without being told to; the page (body) is what is held when there is no shell and this is not set. | | ShowCancelButton | `bool` | true | Shows or hides the cancel button of the Dialog. | | ShowCloseButton | `bool` | true | Shows or hides the close button of the Dialog. | | ShowOkButton | `bool` | true | Shows or hides the ok button of the Dialog. | | Styles | `BitDialogClassStyles?` | null | Custom CSS styles for different parts of the BitDialog component. | | Subtitle | `string?` | null | The secondary line of the header, under the title. | | SubtitleAriaId | `string?` | null | ARIA id for the subtitle of the Dialog, if any. When it is not set, the Dialog describes itself with its own Subtitle, or with its Message when there is no subtitle. | | Title | `string?` | null | The title text to display at the top of the dialog. | | TitleAriaId | `string?` | null | ARIA id for the title of the Dialog, if any. When it is not set, the Dialog names itself with its own Title, and falls back to AriaLabel when there is none. | | TrapFocus | `bool?` | null | Keeps Tab and Shift+Tab cycling inside the Dialog while it is open. Defaults to true for a normal Dialog and false for a modeless one. | | Width | `string?` | null | The CSS width of the Dialog surface. A Dialog is as wide as its content by default, and FullWidth and FullSize take precedence over this. | | 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. | ## Public Members | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | Result | `BitDialogResult?` | null | The result of the last showing of the Dialog: Ok or Cancel when one of those buttons ended it, and null when it was dismissed without an answer or has not been shown yet. | | DismissReason | `BitDialogDismissReason?` | null | What ended the last showing of the Dialog - the gesture that closed it - and null while it is open or before it has been shown at all. It is set before OnDismiss and IsOpenChanged run. | | Show | `Task<BitDialogResult?>` | | Opens the Dialog and waits for it to close, reporting how it closed. | | Open | `Task` | | Opens the Dialog. | | Close | `Task` | | Closes the Dialog the same way its own gestures do: OnDismissing gets its say and can refuse it, DismissReason is named Programmatic, and OnDismiss is invoked once it is done. | | Toggle | `Task` | | Opens the Dialog when it is closed and closes it when it is open. | | 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. | ## Enums ### 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. | ### BitDialogPosition Enum | Name | Value | Description | | :--- | :--- | :---------- | | Center | 0 | Centered both ways. | | TopLeft | 1 | The top left corner, in both reading directions. | | TopCenter | 2 | The top edge, centered horizontally. | | TopRight | 3 | The top right corner, in both reading directions. | | CenterLeft | 4 | The left edge, centered vertically. | | CenterRight | 5 | The right edge, centered vertically. | | BottomLeft | 6 | The bottom left corner, in both reading directions. | | BottomCenter | 7 | The bottom edge, centered horizontally. | | BottomRight | 8 | The bottom right corner, in both reading directions. | | TopStart | 9 | The top edge, on the side the reading direction starts from. | | TopEnd | 10 | The top edge, on the side the reading direction ends at. | | CenterStart | 11 | Centered vertically, on the side the reading direction starts from. | | CenterEnd | 12 | Centered vertically, on the side the reading direction ends at. | | BottomStart | 13 | The bottom edge, on the side the reading direction starts from. | | BottomEnd | 14 | The bottom edge, on the side the reading direction ends at. | ### BitDialogResult Enum | Name | Value | Description | | :--- | :--- | :---------- | | Ok | 0 | The Ok button ended the showing. | | Cancel | 1 | The Cancel button ended the showing. | ### BitDialogDismissReason Enum | Name | Value | Description | | :--- | :--- | :---------- | | OkButton | 0 | The Ok button ended the showing. | | CancelButton | 1 | The Cancel button ended the showing. | | CloseButton | 2 | The close button in the header ended the showing. | | OverlayClick | 3 | A click on the overlay ended the showing. | | Escape | 4 | The Escape key ended the showing. | | Programmatic | 5 | The page closed the Dialog itself, by setting IsOpen or by calling Close or Toggle. | ### BitDialogButton Enum | Name | Value | Description | | :--- | :--- | :---------- | | Ok | 0 | The Ok button, which answers the Dialog with BitDialogResult.Ok. | | Cancel | 1 | The Cancel button, which answers the Dialog with BitDialogResult.Cancel. | | Close | 2 | The close button in the header, which dismisses the Dialog without an answer. | ### 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. | ## Sub Classes ### BitDialogClassStyles Properties | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | Root | `string?` | null | Custom CSS classes/styles for the root element of the BitDialog. | | Document | `string?` | null | Custom CSS classes/styles for the document element of the BitDialog, the layer that holds the overlay and the container and decides where on the screen the Dialog sits. | | Overlay | `string?` | null | Custom CSS classes/styles for the overlay of the BitDialog. | | Container | `string?` | null | Custom CSS classes/styles for the container of the BitDialog. | | Header | `string?` | null | Custom CSS classes/styles for the header of the BitDialog. | | Body | `string?` | null | Custom CSS classes/styles for the body of the BitDialog. | | Title | `string?` | null | Custom CSS classes/styles for the title of the BitDialog. | | Subtitle | `string?` | null | Custom CSS classes/styles for the subtitle of the BitDialog. | | CloseButton | `string?` | null | Custom CSS classes/styles for the close button of the BitDialog. | | CloseIcon | `string?` | null | Custom CSS classes/styles for the icon of the close button of the BitDialog. | | Message | `string?` | null | Custom CSS classes/styles for the message of the BitDialog. | | ButtonsContainer | `string?` | null | Custom CSS classes/styles for the buttons container of the BitDialog. | | Spinner | `string?` | null | Custom CSS classes/styles for the spinner of the ok button of the BitDialog. | | OkButton | `string?` | null | Custom CSS classes/styles for the ok button of the BitDialog. | | CancelButton | `string?` | null | Custom CSS classes/styles for the cancel button of the BitDialog. | | Footer | `string?` | null | Custom CSS classes/styles for the footer of the BitDialog, the element that wraps the FooterTemplate. | ### BitDialogDismissArgs Properties | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | Reason | `BitDialogDismissReason` | | What is about to close the Dialog: one of its three buttons, a click on the overlay, the Escape key, or a call to one of its Close and Toggle methods. | | Cancel | `bool` | false | Set to true to refuse the closing and leave the Dialog where it is. A refused closing shakes the surface and raises OnDismissPrevented with the same reason. | ### BitIconInfo Properties | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | Name | `string?` | null | Gets or sets the name of the icon. | | BaseClass | `string?` | null | Gets or sets the base CSS class for the icon. For built-in Fluent UI icons, this defaults to "bit-icon". For external icon libraries like FontAwesome, you might set this to "fa" or leave empty. | | Prefix | `string?` | null | Gets or sets the CSS class prefix used before the icon name. For built-in Fluent UI icons, this defaults to "bit-icon--". For external icon libraries, you might set this to "fa-" or leave empty. | ## Examples \n**Basic**: ```razor Open Dialog ``` ```csharp private bool IsOpen = false; ``` \n**Buttons**: ```razor Custom labels Single action No close button Open Dialog
``` ```csharp private bool isOpenLabels = false; private bool isOpenAcknowledge = false; private bool isOpenNoClose = false; private bool isOpenGated = false; private bool agreed = false; ``` \n**Header & footer**: ```razor Title & subtitle Header template Footer template
Storage almost full
``` ```csharp private bool isOpenSubtitle = false; private bool isOpenHeaderTemplate = false; private bool isOpenFooterTemplate = false; ``` \n**Custom content**: ```razor Open Dialog
Result is: @customDialogRef?.Result
@if (customDialogRef?.Result == BitDialogResult.Ok) {
Value is: @optionValue
}
All emails together

Your Inbox has changed. No longer does it include favorites, it is a singular destination for your emails.


``` ```csharp private bool IsOpen2 = false; private string? optionValue; private BitDialog customDialogRef = default!; ``` \n**Result**: ```razor Open Dialog
Result is: @(dialogRef?.Result?.ToString() ?? "(none yet)")
Dismiss reason is: @(dialogRef?.DismissReason?.ToString() ?? "-")
Show and await Awaited result is: @awaitedResultText ``` ```csharp private bool IsOpen1 = false; private BitDialog dialogRef = default!; private BitDialog awaitDialogRef = default!; private string awaitedResultText = "(not shown yet)"; private async Task ShowAndAwait() { var result = await awaitDialogRef.Show(); awaitedResultText = result?.ToString() ?? "(dismissed)"; } ``` \n**Events**: ```razor Open Dialog
Last event: @lastEvent
``` ```csharp private bool IsOpenEvent = false; private string lastEvent = "-"; private async Task HandleSlowOk() { lastEvent = "OnOk (working...)"; await Task.Delay(1000); lastEvent = "OnOk"; } ``` \n**Dismiss behavior**: ```razor IsBlocking CloseOnEscape = false IsModeless Blocking with a hint ``` ```csharp private bool IsOpen4 = false; private bool isOpenNoEscape = false; private bool isOpenModeless = false; private bool isOpenPrevented = false; private string? preventedHint; ``` \n**Guarded close**: ```razor Open Dialog
Last refused gesture: @refusedGesture
Result is: @(guardedDialogRef?.Result?.ToString() ?? "(none yet)")
``` ```csharp private bool hasUnsavedChanges = true; private bool isOpenGuarded = false; private string? guardedHint; private string refusedGesture = "-"; private BitDialog guardedDialogRef = default!; private void HandleDismissing(BitDialogDismissArgs args) { // Save is the way out that is always let through, so the Dialog is never a trap. args.Cancel = hasUnsavedChanges && args.Reason is not BitDialogDismissReason.OkButton; } ``` \n**Focus management**: ```razor Default focus behavior AutoFocus & TrapFocus off
Focus the safe answer Focus a field of your own
What can a guest see?
``` ```csharp private bool isOpenFocus = false; private bool isOpenNoFocus = false; private bool isOpenFocusCancel = false; private bool isOpenFocusSelector = false; ``` \n**Absolute position**: ```razor Open Dialog
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams. These placeholder words symbolize the beginning-a moment of possibility where creativity has yet to take shape.
``` ```csharp private bool IsOpen6 = false; ``` \n**Scroll locking**: ```razor AutoToggleScroll ScrollerSelector
Once upon a time, stories wove connections between people, a symphony of voices crafting shared dreams. Each word carried meaning, each pause brought understanding. Placeholder text reminds us of that moment when possibilities are limitless, waiting for content to emerge.
``` ```csharp private bool IsOpen5 = false; private bool IsOpen7 = false; ``` \n**Position**: ```razor Top Left Top Center Top Right Center Left Center Center Right Bottom Left Bottom Center Bottom Right TopLeft TopStart ``` ```csharp private bool IsOpenInPosition = false; private BitDialogPosition position; private bool isOpenPhysical = false; private bool isOpenLogical = false; private void OpenDialogInPosition(BitDialogPosition positionValue) { IsOpenInPosition = true; position = positionValue; } ``` \n**Draggable**: ```razor Open Dialog Open Dialog
Draggable Dialog with custom drag element

Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams. These placeholder words symbolize the beginning-a moment of possibility where creativity has yet to take shape.

``` ```csharp private bool IsDraggable = false; private bool IsOpen8 = false; private bool IsOpen9 = false; ``` \n**Nested dialogs**: ```razor Open Dialog
What changed?
``` ```csharp private bool isOpenOuter = false; private bool isOpenInner = false; ``` \n**Keep mounted**: ```razor KeepMounted Default
``` ```csharp private bool isOpenKeptMounted = false; private bool isOpenUnmounted = false; ``` \n**Programmatic control**: ```razor Open Toggle ``` ```csharp private BitDialog programmaticDialogRef = default!; ``` \n**Color**: ```razor @foreach (var color in dialogColors) { @color } ``` ```csharp private bool isOpenColor = false; private BitColor dialogColor = BitColor.Primary; private readonly BitColor[] dialogColors = Enum.GetValues(); private void OpenDialogInColor(BitColor color) { dialogColor = color; isOpenColor = true; } private async Task HandleColorOk() { await Task.Delay(1000); } ``` \n**External Icons**: ```razor Open Dialog (CloseIcon = fa) Open Dialog (CloseIcon = Css) Open Dialog (CloseIcon = Bi) Open Dialog (CloseIconName) ``` ```csharp private bool IsOpenExtIcon1 = false; private bool IsOpenExtIcon2 = false; private bool IsOpenExtIcon3 = false; private bool IsOpenExtIcon4 = false; ``` \n**Size**: ```razor Width MaxWidth & MinWidth Height & MaxHeight FullWidth FullSize

The surface keeps its height whatever it holds, and the body scrolls inside it while the header above and the buttons below stay where they are.

``` ```csharp private bool isOpenSized = false; private bool isOpenResponsive = false; private bool isOpenTall = false; private bool isOpenFullWidth = false; private bool isOpenFullSize = false; ``` \n**Style & Class**: ```razor Styles Classes ``` ```csharp private bool isOpenStyles = false; private bool isOpenClasses = false; ``` \n**RTL**: ```razor باز کردن پنجره پیام ``` ```csharp private bool IsOpen10 = false; ```