Skip to main content

Blazor Modal

Use Blazor Bootstrap modal component to add dialogs to your site for lightboxes, user notifications, or completely custom content.

Parameters

NameTypeDefaultRequiredDescriptionAdded Version
BodyCssClassstringnullGets or sets the body CSS class.1.0.0
BodyTemplateRenderFragmentnullGets or sets the body template.1.0.0
CloseIconColorIconColorIconColor.NoneGets or sets the close icon color.1.0.0
CloseOnEscapebooltrueIndicates whether the modal closes when escape key is pressed.1.0.0
DialogCssClassstringnullGets or sets the modal dialog (div.modal-dialog) CSS class.1.0.0
FooterCssClassstringnullGets or sets the footer CSS class.1.0.0
FooterTemplateRenderFragmentnullGets or sets the footer template.1.0.0
FullscreenModalFullscreenModalFullscreen.DisabledGets or sets the fullscreen behavior of the modal.1.0.0
HeaderCssClassstringnullGets or sets the header CSS class.1.0.0
HeaderTemplateRenderFragmentnullGets or sets the header template.1.0.0
IsScrollableboolfalseIf true, scroll will be enabled on the modal body.1.0.0
IsServiceModalboolfalseIndicates whether the modal is related to a modal service or not.1.9.4
IsVerticallyCenteredboolfalseIf true, shows the modal vertically in the center.1.0.0
MessagestringnullGets or sets the message.1.0.0
ModalTypeModalTypeModalType.LightGets or sets the modal type.1.9.5
ShowCloseButtonbooltrueIf true, close button will be visible in the modal header.1.0.0
SizeModalSizeModalSize.RegularGets or sets the modal size.1.0.0
TabIndexint-1Gets or sets the tab index.1.6.0
TitlestringnullGets or sets the modal header title.1.0.0
UseStaticBackdropboolfalseIndicates whether the modal uses a static backdrop.1.0.0

Methods

NameDescriptionAdded Version
ShowAsyncOpens a modal.1.0.0
ShowAsync<T>(string title, Dictionary<string, object> parameters = null)Opens a modal. T is component.1.4.1
HideAsyncHides a modal.1.0.0
Asynchronous methods and transitions

All API methods are asynchronous and start a transition. They return to the caller as soon as the transition is started but before it ends. In addition, a method call on a transitioning component will be ignored.

Callback Events

EventDescription
OnShowingThis event fires immediately when the show instance method is called.
OnShownThis event is fired when an offcanvas element has been made visible to the user (will wait for CSS transitions to complete).
OnHidingThis event is fired immediately when the hide method has been called.
OnHiddenThis event is fired when an offcanvas element has been hidden from the user (will wait for CSS transitions to complete).
OnHidePreventedThis event is fired when the modal is shown, its backdrop is static and a click outside the modal or an escape key press is performed with the keyboard option or data-bs-keyboard set to false.

How it works

Before getting started with BlazorBootstrap's modal component, be sure to read the following as our menu options have recently changed.

  • Modals are built with HTML, CSS, and JavaScript. They're positioned over everything else in the document and remove scroll from the <body> so that modal content scrolls instead.
  • Clicking on the modal "backdrop" will automatically close the modal.
  • BlazorBootstrap only supports one modal window at a time. Nested modals aren't supported as we believe them to be poor user experiences.

Examples

Clicking the Show Modal button below, the modal will slide down and fade in from the top of the page.

Blazor Modal Component
<Modal @ref="modal" Title="Modal title">
<BodyTemplate>
Modal body text goes here.
</BodyTemplate>
<FooterTemplate>
<Button Color="ButtonColor.Secondary" @onclick="OnHideModalClick">Close</Button>
<Button Color="ButtonColor.Primary">Save changes</Button>
</FooterTemplate>
</Modal>

<Button Color="ButtonColor.Primary" @onclick="OnShowModalClick">Show Modal</Button>
@code {
private Modal modal;

private async Task OnShowModalClick()
{
await modal?.ShowAsync();
}

private async Task OnHideModalClick()
{
await modal?.HideAsync();
}
}

See demo here.

Dynamic component as modal

Render different components dynamically within the modal without iterating through possible types or using conditional logic. If dynamically-rendered components have component parameters, pass them as an IDictionary. The string is the parameter's name, and the object is the parameter's value.

Blazor Modal Component - Dynamic component as modal
<Modal @ref="modal" />

<Button Color="ButtonColor.Primary" @onclick="OnShowModalClick">Show Employee Component</Button>

@code {
private Modal modal = default!;
private string? message;

private async Task OnShowModalClick()
{
var parameters = new Dictionary<string, object>();
parameters.Add("EmployeeId", 321);
await modal.ShowAsync<EmployeeDemoComponent1>(title: "Employee Details", parameters: parameters);
}
}

EmployeeDemoComponent1.razor

<div class="row">
<div class="col-5 col-md-3 text-end">Employee Id :</div>
<div class="col-7 col-md-9">@EmployeeId</div>
</div>
<div class="row">
<div class="col-5 col-md-3 text-end">First Name :</div>
<div class="col-7 col-md-9">@employee.FirstName</div>
</div>
<div class="row">
<div class="col-5 col-md-3 text-end">Last Name :</div>
<div class="col-7 col-md-9">@employee.LastName</div>
</div>

@code {
private Employee employee;

[Parameter] public int EmployeeId { get; set; }

protected override void OnInitialized()
{
// get employee with {EmployeeId} from DB

employee = new Employee { FirstName = "Vikram", LastName = "Reddy" };

base.OnInitialized();
}
}

See demo here.

Pass event callbacks to a dynamic component

Event callbacks (EventCallback) can be passed in its parameter dictionary. In the following parent component example, the ShowDTMessage method assigns a string with the current time to message, and the value of message is rendered. The parent component passes the callback method, ShowDTMessage in the parameter dictionary:

  • The string key is the callback method's name, OnClickCallback.
  • The object value is created by EventCallbackFactory.Create for the parent callback method, ShowDTMessage.
Blazor Modal Component - Pass event callbacks to a dynamic component
<Modal @ref="modal" />

<Button Color="ButtonColor.Primary" @onclick="OnShowModalClick">Show Employee Component</Button>

<div class="mt-3">
@message
</div>

@code {
private Modal modal = default!;
private string? message;

private async Task OnShowModalClick()
{
var parameters = new Dictionary<string, object>();
parameters.Add("EmployeeId", 322);
parameters.Add("OnclickCallback", EventCallback.Factory.Create<MouseEventArgs>(this, ShowDTMessage));
await modal.ShowAsync<EmployeeDemoComponent2>(title: "Employee Details", parameters: parameters);
}

private void ShowDTMessage(MouseEventArgs e) => message = $"The current DT is: {DateTime.Now}.";
}

EmployeeDemoComponent2.razor

<div class="row">
<div class="col-5 col-md-3 text-end">Employee Id :</div>
<div class="col-7 col-md-9">@EmployeeId</div>
</div>
<div class="row">
<div class="col-5 col-md-3 text-end">First Name :</div>
<div class="col-7 col-md-9">@employee.FirstName</div>
</div>
<div class="row">
<div class="col-5 col-md-3 text-end">Last Name :</div>
<div class="col-7 col-md-9">@employee.LastName</div>
</div>

<Button class="mt-3" Color="ButtonColor.Success" Type="ButtonType.Button" @onclick="OnClickCallback">
Trigger a Parent component method
</Button>

@code {
private Employee employee;

[Parameter] public int EmployeeId { get; set; }

[Parameter] public EventCallback<MouseEventArgs> OnClickCallback { get; set; }

protected override void OnInitialized()
{
// get employee with {EmployeeId} from DB

employee = new Employee { FirstName = "Sagar", LastName = "Reddy" };

base.OnInitialized();
}
}

See demo here.

Static backdrop

When UseStaticBackdrop is set to true, the modal will not close when clicking outside it. CloseOnEscape should also be set to false to ignore the effect of pressing the Esc key and mimic the original behaviour of Bootstrap modal. Click the button below to try it.

Blazor Modal Component - Static backdrop
<Modal @ref="modal" title="Modal title" UseStaticBackdrop="true" CloseOnEscape="false">
<BodyTemplate>
I will not close if you click outside me. Don't even try to press escape key.
</BodyTemplate>
<FooterTemplate>
<Button Color="ButtonColor.Secondary" @onclick="OnHideModalClick">Close</Button>
<Button Color="ButtonColor.Primary">Understood</Button>
</FooterTemplate>
</Modal>

<Button Color="ButtonColor.Primary" @onclick="OnShowModalClick">Launch static backdrop modal</Button>
@code {
private Modal modal;

private async Task OnShowModalClick()
{
await modal?.ShowAsync();
}

private async Task OnHideModalClick()
{
await modal?.HideAsync();
}
}

See demo here.

Scrolling long content

When modals become too long for the user’s viewport or device, they scroll independent of the page itself. Try the demo below to see what we mean.

Blazor Modal Component - Scrolling long content
<Modal @ref="modal" title="Modal title" IsScrollable="true">
<BodyTemplate>
<p style="margin-bottom: 100vh;">This is some placeholder content to show the scrolling behavior for modals. Instead of repeating the text the modal, we use an inline style set a minimum height, thereby extending the length of the overall modal and demonstrating the overflow scrolling. When content becomes longer than the height of the viewport, scrolling will move the modal as needed.</p>
<p>This content should appear at the bottom after you scroll.</p>
</BodyTemplate>
<FooterTemplate>
<Button Color="ButtonColor.Secondary" @onclick="OnHideModalClick">Close</Button>
<Button Color="ButtonColor.Primary">Save changes</Button>
</FooterTemplate>
</Modal>

<Button Color="ButtonColor.Primary" @onclick="OnShowModalClick">Launch demo modal</Button>
@code {
private Modal modal;

private async Task OnShowModalClick()
{
await modal?.ShowAsync();
}

private async Task OnHideModalClick()
{
await modal?.HideAsync();
}
}

See demo here.

Vertically centered

Add IsVerticallyCentered="true" to vertically center the modal.

Blazor Modal Component - Vertically centered
<Modal @ref="modal" title="Modal title" IsVerticallyCentered="true">
<BodyTemplate>
This is a vertically centered modal.
</BodyTemplate>
<FooterTemplate>
<Button Color="ButtonColor.Secondary" @onclick="OnHideModalClick">Close</Button>
<Button Color="ButtonColor.Primary">Save changes</Button>
</FooterTemplate>
</Modal>

<Button Color="ButtonColor.Primary" @onclick="OnShowModalClick">Vertically centered modal</Button>
@code {
private Modal modal;

private async Task OnShowModalClick()
{
await modal?.ShowAsync();
}

private async Task OnHideModalClick()
{
await modal?.HideAsync();
}
}

See demo here.

Vertically centered and scrollable

Blazor Modal Component - Vertically centered and scrollable
<Modal @ref="modal" title="Modal title" IsVerticallyCentered="true" IsScrollable="true">
<BodyTemplate>
<p style="margin-bottom: 100vh;">This is some placeholder content to show the scrolling behavior for modals. Instead of repeating the text the modal, we use an inline style set a minimum height, thereby extending the length of the overall modal and demonstrating the overflow scrolling. When content becomes longer than the height of the viewport, scrolling will move the modal as needed.</p>
<p>This content should appear at the bottom after you scroll.</p>
</BodyTemplate>
<FooterTemplate>
<Button Color="ButtonColor.Secondary" @onclick="OnHideModalClick">Close</Button>
<Button Color="ButtonColor.Primary">Save changes</Button>
</FooterTemplate>
</Modal>

<Button Color="ButtonColor.Primary" @onclick="OnShowModalClick">Vertically centered scrollable modal</Button>
@code {
private Modal modal;

private async Task OnShowModalClick()
{
await modal?.ShowAsync();
}

private async Task OnHideModalClick()
{
await modal?.HideAsync();
}
}

See demo here.

Optional sizes

Modals have three optional sizes. These sizes kick in at certain breakpoints to avoid horizontal scrollbars on narrower viewports.

Blazor Modal Component - Optional sizes
<Modal @ref="xlModal" title="Extra large modal" Size="ModalSize.ExtraLarge">
<BodyTemplate>...</BodyTemplate>
</Modal>
<Modal @ref="lgModal" title="Large modal" Size="ModalSize.Large">
<BodyTemplate>...</BodyTemplate>
</Modal>
<Modal @ref="smModal" title="Small modal" Size="ModalSize.Small">
<BodyTemplate>...</BodyTemplate>
</Modal>

<Button Color="ButtonColor.Primary" @onclick="() => xlModal?.ShowAsync()">Extra large modal</Button>
<Button Color="ButtonColor.Primary" @onclick="() => lgModal?.ShowAsync()">Large modal</Button>
<Button Color="ButtonColor.Primary" @onclick="() => smModal?.ShowAsync()">Small modal</Button>
@code {
private Modal xlModal;
private Modal lgModal;
private Modal smModal;
}

See demo here.

Fullscreen Modal

Blazor Modal Component - Fullscreen Modal
<Modal @ref="modal" title="Full screen" Fullscreen="ModalFullscreen.Always">
<BodyTemplate>...</BodyTemplate>
</Modal>
<Modal @ref="smModal" title="Full screen below sm" Fullscreen="ModalFullscreen.SmallDown">
<BodyTemplate>...</BodyTemplate>
</Modal>
<Modal @ref="mdModal" title="Full screen below md" Fullscreen="ModalFullscreen.MediumDown">
<BodyTemplate>...</BodyTemplate>
</Modal>
<Modal @ref="lgModal" title="Full screen below lg" Fullscreen="ModalFullscreen.LargeDown">
<BodyTemplate>...</BodyTemplate>
</Modal>
<Modal @ref="xlModal" title="Full screen below xl" Fullscreen="ModalFullscreen.ExtraLargeDown">
<BodyTemplate>...</BodyTemplate>
</Modal>
<Modal @ref="xxlModal" title="Full screen below xxl" Fullscreen="ModalFullscreen.ExtraExtraLargeDown">
<BodyTemplate>...</BodyTemplate>
</Modal>

<Button Color="ButtonColor.Primary" @onclick="() => modal?.ShowAsync()">Full screen</Button>
<Button Color="ButtonColor.Primary" @onclick="() => smModal?.ShowAsync()">Full screen below sm</Button>
<Button Color="ButtonColor.Primary" @onclick="() => mdModal?.ShowAsync()">Full screen below md</Button>
<Button Color="ButtonColor.Primary" @onclick="() => lgModal?.ShowAsync()">Full screen below lg</Button>
<Button Color="ButtonColor.Primary" @onclick="() => xlModal?.ShowAsync()">Full screen below xl</Button>
<Button Color="ButtonColor.Primary" @onclick="() => xxlModal?.ShowAsync()">Full screen below xxl</Button>
@code {
private Modal modal;
private Modal smModal;
private Modal mdModal;
private Modal lgModal;
private Modal xlModal;
private Modal xxlModal;
}

See demo here.

Callback Events

BlazorBootstrap's modal class exposes a few events for hooking into modal functionality.

<Modal @ref="modal"
title="Modal title"
OnShowing="OnModalShowingAsync"
OnShown="OnModalShownAsync"
OnHiding="OnModalHidingAsync"
OnHidden="OnModalHiddenAsync"
OnHidePrevented="OnModalHidePreventedAsync">

<BodyTemplate>
Modal body text goes here.
</BodyTemplate>

<FooterTemplate>
<Button Color="ButtonColor.Secondary" @onclick="OnHideModalClick">Close</Button>
<Button Color="ButtonColor.Primary">Save changes</Button>
</FooterTemplate>

</Modal>

<Button Color="ButtonColor.Primary" @onclick="OnShowModalClick">Show Modal</Button>
@code {
private Modal modal;

private async Task OnModalShowingAsync()
{
await Task.Run(() => { Console.WriteLine("Event: Showing"); });
}

private async Task OnModalShownAsync()
{
await Task.Run(() => { Console.WriteLine("Event: Show"); });
}

private async Task OnModalHidingAsync()
{
await Task.Run(() => { Console.WriteLine("Event: Hiding"); });
}

private async Task OnModalHiddenAsync()
{
await Task.Run(() => { Console.WriteLine("Event: Hide"); });
}

private async Task OnModalHidePreventedAsync()
{
await Task.Run(() => { Console.WriteLine("Event: Hide Prevented"); });
}
}

See demo here.