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​

NameTypeDescriptionRequiredDefaultAdded Version
BodyCssClassstringAdditional body CSS class.1.0.0
BodyTemplateRenderFragmentBody template.βœ”οΈ1.0.0
ChildContentRenderFragmentSpecifies the content to be rendered inside the alert.1.0.0
CloseOnEscapeboolIndicates whether the modal closes when escape key is pressed.true1.0.0
DialogCssClassstringAdditional CSS class for the dialog (div.modal-dialog element).1.0.0
FooterCssClassstringFooter css class.1.0.0
FooterTemplateRenderFragmentFooter template.βœ”οΈ1.0.0
FullscreenModalFullscreenFullscreen behavior of the modal.ModalFullscreen.Disabled1.0.0
HeaderTemplateRenderFragmentHeader template.βœ”οΈ1.0.0
HeaderCssClassstringAdditional header CSS class.1.0.0
IsScrollableboolAllows modal body scroll.false1.0.0
IsServiceModalboolIndicates whether the modal is related to a modal service or not.false1.9.4
IsVerticallyCenteredboolShows the modal vertically in the center.false1.0.0
ModalTypeModalTypeGets or sets the modal type.ModalType.Light1.9.5
SizeModalSizeSize of the modal.ModalSize.Regular1.0.0
ShowCloseButtonboolIndicates whether the modal shows close button in header.true1.0.0
TabIndexintGets or sets the tab index.-11.6.0
Titlestringβœ”οΈ1.0.0
UseStaticBackdropboolIndicates whether the modal uses a static backdrop.false1.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.