DOCSEARCHbyAlgolia
Submit Docs

Blazored Modal Documentation

repository·main·Indexed 21 days ago

https://github.com/blazored/modal

A customizable library for Blazor applications providing a powerful implementation for displaying and managing modal windows. It includes features for configuring modal sizes, positions, animations, and accessibility options like focus traps, as well as global and instance-level configuration via CascadingBlazoredModal and ModalOptions.

Tokens
6.9K
Snippets
39
Records
42
Agent score
73%

What's inside Blazored Modal

  1. Overview of Blazored Modal

    main
    Blazored Modal is a powerful and customizable modal implementation designed specifically for Blazor applications. It allows developers to easily trigger and manage modal windows within their Blazor UI.

  2. Configure modal position using ModalPosition

    main

    By default, modals are centered near the top of the viewport. You can change this behavior using the Position option, which accepts a ModalPosition enum value.

    Available predefined positions:

    • ModalPosition.TopLeft
    • ModalPosition.TopRight
    • ModalPosition.TopCenter
    • ModalPosition.Middle
    • ModalPosition.BottomLeft
    • ModalPosition.BottomRight
    • ModalPosition.Custom

  3. Implement a component for use in Blazored Modal

    main

    When creating a component to be displayed in a modal, you should define the data you wish to receive as standard Blazor [Parameter] properties. To allow the component to close itself, include a [CascadingParameter] of type BlazoredModalInstance.

    <div class="modal-content">
    <p>@Message</p>
    <button @onclick="Close">Close</button>
</div>

@code {
    [CascadingParameter] BlazoredModalInstance BlazoredModal { get; set; } = default!;

    [Parameter] public string? Message { get; set; }

    private async Task Close() => await BlazoredModal.CloseAsync();
}

  4. Hide the header for a single modal using ModalOptions

    main

    To hide the header for a specific modal instance, create a ModalOptions object and set the HideHeader property to true. Pass this options object as the second argument to the Modal.Show<T> method.

    var options = new ModalOptions() 
{
    HideHeader = true 
};

Modal.Show<Confirm>("Are you sure?", options);

  7. Show multiple modals sequentially or stacked

    main

    Blazored Modal allows displaying multiple modals simultaneously. To stack modals, you must trigger the opening of a new modal from the currently active modal instance using the IModalService.

    When a new modal is shown from an existing one, it will render on top of the current modal. If you wish to close the underlying modal after the new one is dismissed, you can await the Result of the new modal and then call CloseAsync() on the current BlazoredModalInstance.

    @* Inside the first modal (ModalOne.razor) *@

[CascadingParameter] BlazoredModalInstance ModalOne { get; set; } = default!;
[CascadingParameter] IModalService ModalService { get; set; } = default!;

private async Task ShowModalTwo()
{
    // 1. Show the second modal from the first one
    var modalTwo = ModalService.Show<ModalTwo>("Second Modal");
    
    // 2. Wait for the second modal to be closed
    _ = await modalTwo.Result;

    // 3. Close the first modal
    await ModalOne.CloseAsync();
}

  9. Retrieve data from a modal result

    main

    When a modal is invoked using Modal.Show<T>(), you can retrieve the returned data by awaiting the Result property of the returned modal instance.

    To safely access the data, check the Confirmed property of the ModalResult. If Confirmed is true, you can access the returned value via the Data property. Note that Data is returned as an object, so you may need to cast it or call .ToString() depending on your requirements.

    var messageForm = Modal.Show<MessageForm>();
var result = await messageForm.Result;

if (result.Confirmed)
{
    // Access the returned data via the Data property
    _message = result.Data.ToString();
}

  10. Configure predefined modal sizes

    main

    Blazored Modal provides several built-in sizes. If no size is specified, the default is ModalSize.Medium.

    Available predefined sizes:

    • ModalSize.Small (300px)
    • ModalSize.Medium (500px)
    • ModalSize.Large (800px)
    • ModalSize.ExtraLarge (1140px)
    • Automatic (Size determined by content)

    You can apply a predefined size globally via the CascadingBlazoredModal component or for a specific instance using ModalOptions passed to the Show method.

    <!-- Global configuration -->
<CascadingBlazoredModal Size="ModalSize.Large" />
    // Single modal configuration
var options = new ModalOptions() 
{
    Size = ModalSize.Large 
};

Modal.Show<Confirm>("Are you sure?", options);

  11. Await the result of a modal

    main

    When opening a modal using IModalService.Show<TComponent>, you can capture a reference to the modal instance and await its Result property. This allows you to perform logic based on whether the user confirmed the action or cancelled the modal.

    The Result object provides two boolean properties:

    • Cancelled: True if the modal was closed without confirmation.
    • Confirmed: True if the modal was closed via a confirmation action.

    To use this, inject IModalService as a [CascadingParameter] into your component.

    @page "/movies"

<h1 @onclick="ShowModal">Movies</h1>
<button @onclick="ShowModal">View Movies</button>

@code {
    [CascadingParameter] IModalService Modal { get; set; } = default!;

    private async Task ShowModal()
    {
        // Capture the reference to the modal instance
        var moviesModal = Modal.Show<Movies>("My Movies");
        
        // Await the result
        var result = await moviesModal.Result;

        if (result.Cancelled)
        {
            Console.WriteLine("Modal was cancelled");
        }
        else if (result.Confirmed)
        {
            Console.WriteLine("Modal was closed");
        }
    }
}

  12. Customize Modal Styles

    main

    You can override the default look of Blazored Modal by providing your own CSS classes. These custom classes will replace the default style classes applied by the library, giving you complete control over the modal's appearance.

    Depending on your needs, you can apply these styles globally to all modals or specifically to a single modal instance.

    // Example of applying a custom class to a single modal
var options = new ModalOptions() 
{
    Class = "my-custom-modal-class"
};

Modal.Show<Confirm>("Are you sure?", options);