LgModal

LgModal displays content in a modal window: title with icon, body (ChildContent), footer (FooterContent), and optional toolbar. The window is draggable, closes via the close button or programmatically, and requests confirmation if a tracked form (LgFormTracker) has unsaved changes.

<LgModal Title="#EditOrder" @bind-Visible="_modalVisible">
    ...
</LgModal>

• Namespace : Lagoon.UI.Components
• Inherits from : LgAriaComponentBase → LgComponentBase
• Interfaces : IPageTitleHandler, IFormTrackerHandler, ICommandListener
• NuGet package : Lagoon.UI

Infrastructure

Modal rendering relies on LgModalContainer, an infrastructure component registered by the application layout — you don't need to declare it.

Usage

Demonstration

Try this component in the Lagoon showcase.

Open and close a modal

Control visibility with Visible (two-way binding with @bind-Visible) or using ShowAsync() / CloseAsync() methods via @ref. CloseAsync() respects close confirmation; the header close button follows the same path.

OrderPage.razor

<LgButton Text="#EditOrder" OnClick="OpenModalAsync" />

<LgModal Title="#EditOrder"
         IconName="@IconNames.All.Pencil"
         @bind-Visible="_modalVisible">
    <ChildContent>
        <LgTextBox Label="#Reference" @bind-Value="_model.Reference" />
    </ChildContent>
    <FooterContent>
        <LgButton Text="#Save" OnClick="SaveAsync" />
    </FooterContent>
</LgModal>

OrderPage.razor.cs

public partial class OrderPage : LgPage
{
    // Modal visibility: bound with @bind-Visible to also track close button clicks.
    private bool _modalVisible;

    private readonly OrderVm _model = new();

    // Opens the edit modal.
    private Task OpenModalAsync(ActionEventArgs args)
    {
        _modalVisible = true;
        return Task.CompletedTask;
    }

    // Persists the input and closes the modal.
    private async Task SaveAsync(ActionEventArgs args)
    {
        await Task.Delay(100, args.CancellationToken);
        _modalVisible = false;
        ShowSuccess("#OrderSaved");
    }

    private sealed class OrderVm
    {
        public string Reference { get; set; }
    }
}

Control close behavior

OnClose is triggered before closing: set args.Cancel to prevent it (incomplete input, processing in progress…). Closable="false" hides the close button and BackgroundClose allows closing by clicking the background.

WizardPage.razor

<LgModal Title="#WizardStep"
         Closable="true"
         BackgroundClose="false"
         OnClose="OnModalClosing"
         @bind-Visible="_modalVisible">
    ...
</LgModal>

WizardPage.razor.cs

public partial class WizardPage : LgPage
{
    private bool _modalVisible;

    // Indicates that processing is in progress and closing should be blocked.
    private bool _isProcessing;

    // Triggered before close: set args.Cancel to prevent closing.
    private void OnModalClosing(CloseModalEventArgs args)
    {
        if (_isProcessing)
        {
            args.Cancel = true;
            ShowWarning("#ProcessingInProgress");
        }
    }
}

Size, position, and movement

ModalSize sets the width, Centered vertically centers the window, and Draggable (enabled by default) allows moving it; a header icon toggles between constrained movement within the window and free movement.

PreviewPage.razor

<LgModal Title="#Preview"
         ModalSize="ModalSize.ExtraLarge"
         Centered="true"
         Draggable="false"
         @bind-Visible="_modalVisible">
    ...
</LgModal>

PreviewPage.razor.cs

public partial class PreviewPage : LgPage
{
    private bool _modalVisible;
}

Toolbar and summary

Toolbar inserts a toolbar in the header and Summary adds a description below the title. The modal also listens to commands raised by its children: the CloseModal command closes it.

DocumentPage.razor

<LgModal Title="#Document" Summary="#DocumentModalSummary" @bind-Visible="_modalVisible">
    <Toolbar>
        <LgToolbar>
            <LgToolbarButton Text="#Print" IconName="@IconNames.All.Printer" CommandName="print" />
        </LgToolbar>
    </Toolbar>
    <ChildContent>
        ...
    </ChildContent>
</LgModal>

DocumentPage.razor.cs

public partial class DocumentPage : LgPage
{
    private bool _modalVisible;
}

Display a page in a modal

LgModal implements IPageTitleHandler: a LgPage displayed in the modal automatically passes its title, icon, and CSS class if Title / IconName are not set on the modal.

Properties

All [Parameter] properties of the component, including inherited ones.

Name	Type	Default	Declared in	Description
AdditionalAttributes	IReadOnlyDictionary<string, object>	null	LgModal	Additional HTML attributes applied to the rendered element.
BackgroundClose	bool?	null	LgModal	Allows closing by clicking the background.
Centered	bool	false	LgModal	Vertically centers the window.
ChildContent	RenderFragment	null	LgModal	Content of the modal body.
Closable	bool	true	LgModal	Shows the close button.
CssClass	string	null	LgModal	Additional CSS classes.
DefaultVisible	bool?	null	LgModal	Initial visibility of the modal (applied at initialization).
Draggable	bool	true	LgModal	Allows moving the window.
FooterContent	RenderFragment	null	LgModal	Footer content (action buttons).
IconName	string	null	LgModal	Header icon. If null, the icon of the displayed LgPage is used.
ModalSize	ModalSize	Medium	LgModal	Size (width) of the window.
OnClose	EventCallback<CloseModalEventArgs>	—	LgModal	Callback called before closing; args.Cancel = true prevents it.
Summary	string	null	LgModal	Description displayed below the title.
Title	string	null	LgModal	Title of the modal. If null, the title of the displayed LgPage is used.
Toolbar	RenderFragment	null	LgModal	Toolbar displayed in the header.
Visible	bool	true	LgModal	Shows or hides the modal (@bind-Visible).
VisibleChanged	EventCallback<bool>	—	LgModal	Callback for updating Visible.
AriaLabel	string	null	LgAriaComponentBase	Value of the aria-label attribute.
AriaLabelledBy	string	(header id)	LgAriaComponentBase	Value of the aria-labelledby attribute. By default, the modal is linked to its header.

Cascading parameters

LgModal also consumes parameters automatically provided by ancestor components: FormTracker (LgFormTracker), the parent command handler (ICommandListener), and the parent form tracking handler (IFormTrackerHandler).

Methods & events

Member	Signature	Description
ShowAsync	Task ShowAsync()	Shows the modal.
CloseAsync	Task CloseAsync()	Requests closing: confirmation if a tracked form has changes, then OnClose.
OnClose	EventCallback<CloseModalEventArgs>	Before closing; args.Cancel = true prevents it.
VisibleChanged	EventCallback<bool>	On each visibility change (@bind-Visible).

Associated enumerations

ModalSize

Width of the modal window.

Value	Description
Small	300 px.
Medium	500 px (default).
Large	800 px.
ExtraLarge	1140 px.
ExtraExtraLarge	1600 px.

Best practices / accessibility

• The modal is automatically linked to its header by aria-labelledby: always give it an explicit Title (or AriaLabel).
• Place validation actions in FooterContent and keep the body for input; the CloseModal command allows a child button to close the modal without a direct reference.
• See the Accessibility page for RGAA rules applied by the framework (focus, roles, keyboard navigation).

Complete reference

All parameters (including inherited ones): API Reference — LgModal.

Related components

• LgSummaryBox — long text field edited in a modal.
• LgEditForm — form whose change tracking triggers close confirmation.