Skip to main content

DxPopup Class

A modal popup window with custom content that overlays the current view.

Namespace: DevExpress.Blazor

Assembly: DevExpress.Blazor.v24.1.dll

NuGet Package: DevExpress.Blazor

Declaration

public class DxPopup :
    DxPopupBase

Remarks

The DevExpress Popup for Blazor allows you to show a modal pop-up window. The window traps focus and users cannot access HTML elements located outside the window until it is closed.

Blazor Popup

Run Demo: Popup - Overview

Add a Popup to a Project

Follow the steps below to add the Popup component to an application:

  1. Use a DevExpress Project Template to create a new Blazor Server or Blazor WebAssembly application. If you use a Microsoft project template or already have a Blazor project, configure your project to incorporate DevExpress Blazor components.
  2. Add the <DxPopup></DxPopup> markup to a .razor file.
  3. Write code that manages the Popup’s visibility.
  4. Define the Popup’s content and appearance.
  5. Configure other options (see the sections below).

The Popup component renders in a root pop-up container that is placed directly in the document body. See the example of the HTML markup below. You do not need to copy this sample, as Popup generates this markup automatically.

<body>
    <!-- ... -->
    <dxbl-popup-root>
        <!-- ... -->
        <dxbl-modal>
            <!-- Popup render -->
        </dxbl-modal>
        <!-- ... -->
    </dxbl-popup-root>
</body>

This behavior allows Popup to display correctly and prevent parent elements and CSS rules from clipping or corrupting the content.

Show and Close a Popup

Implement two-way binding for the Visible property to show the Popup in code and update the property value when a user closes the Popup.

<div @onclick="@(() => PopupVisible = true)">
    <p>CLICK TO SHOW A POP-UP WINDOW</p>
</div>

<DxPopup @bind-Visible="@PopupVisible">
</DxPopup>

@code {
    bool PopupVisible { get; set; } = false;
}

Call the ShowAsync and CloseAsync methods to show and close the Popup asynchronously. Make sure the component has been initialized before you call the ShowAsync method. Use the IsInitialized property to check the initialization state.

User Capabilities

Users can close the Popup in the following ways:

  • Click the Close button in the header.
  • Click outside the Popup’s boundaries.
  • Press Escape.

Set the ShowCloseButton, CloseOnOutsideClick, and CloseOnEscape properties to false to disable these user capabilities.

Drag a Popup

Set the AllowDrag property to true to allow users to drag the Popup by its header to a new position. You can disable the AllowDragByHeaderOnly option to allow dragging by every window element – header, body, or footer.

<div @onclick="@(() => PopupVisible = true)">
    <p>CLICK TO SHOW A POP-UP WINDOW</p>
</div>

<DxPopup @bind-Visible="@PopupVisible"
         HeaderText="Header"
         BodyText="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris sit amet metus vel
                   nisi blandit tincidunt vel efficitur purus. Nunc nec turpis tempus, accumsan orci auctor,
                   imperdiet mauris. Fusce id purus magna."
         AllowDrag="true">
</DxPopup>

@code {
    bool PopupVisible { get; set; } = false;
}

Drag the modal component

You can handle the following events to process drag actions:

DragStarted
Fires when a user drags the Popup or resizes it by edges.
DragCompleted
Fires when a user drops the Popup.

Run Demo: Dragging

Content and Appearance

The Popup consists of body and header with the Close button. Disable the ShowHeader option to hide the header. You can also enable the ShowFooter option to display the Popup footer.

Display Text

Use the HeaderText, BodyText, and FooterText properties to specify text displayed in Popup elements. All predefined appearance settings apply to these elements.

<div @onclick="@(() => PopupVisible = true)">
    <p>CLICK TO SHOW A POP-UP WINDOW</p>
</div>

<DxPopup @bind-Visible="@PopupVisible"
         HeaderText="Header"
         BodyText="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris sit amet metus vel
             nisi blandit tincidunt vel efficitur purus. Nunc nec turpis tempus, accumsan orci auctor,
             imperdiet mauris. Fusce id purus magna." />

@code {
    bool PopupVisible { get; set; } = false;
}

Blazor Popup

To customize appearance of Popup elements, assign CSS classes to the HeaderCssClass, BodyCssClass, and FooterCssClass properties.

Run Demo: Popup - Overview

Display Custom Content

Use HeaderContentTemplate, BodyContentTemplate, and FooterContentTemplate properties to display any UI render fragment in Popup elements. A render fragment can include formatted text, images, or another component. These templates affect the content area only.

This template replaces the default content but keeps the predefined space between the content area and border. The header’s content area does not include the Close button. The following image highlights the content area in red:

Blazor Popup Content Area

These templates take priority over the *Text and *CssClass properties described above.

Each template accepts an IPopupElementInfo object as the context parameter. You can use the parameter’s CloseCallback property to implement the Close button.

<div @onclick="@(() => PopupVisible = true)">
    <p>CLICK TO SHOW A POP-UP WINDOW</p>
</div>

<DxPopup @bind-Visible="@PopupVisible"
         HeaderText="Header"
         ShowFooter="true">
    <BodyContentTemplate>
        <i>
            Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris sit amet metus vel
            nisi blandit tincidunt vel efficitur purus. Nunc nec turpis tempus, accumsan orci auctor,
            imperdiet mauris. Fusce id purus magna.
        </i>
    </BodyContentTemplate>
    <FooterContentTemplate>
        <DxButton RenderStyle="ButtonRenderStyle.Primary" Text="OK"
                  Click="@context.CloseCallback" />
    </FooterContentTemplate>
</DxPopup>

@code {
    bool PopupVisible { get; set; } = false;
}

Blazor Popup Content Templates

Run Demo: Popup - Customization

Customize Entire Elements

Specify HeaderTemplate, BodyTemplate, and FooterTemplate properties to define content and appearance of Popup elements. Predefined appearance settings do not apply. You can display any UI render fragment (for instance, formatted text, images, or another component).

These templates substitute entire render fragments of the corresponding elements. Predefined appearance settings, content alignment and paddings, and the corresponding Text, CssClass, and ContentTemplate properties have no effect.

Each template accepts an IPopupElementInfo object as the context parameter. You can use the parameter’s CloseCallback property to implement the Close button.

<div @onclick="@(() => PopupVisible = true)">
    <p>CLICK TO SHOW A POP-UP WINDOW</p>
</div>

<DxPopup @bind-Visible="@PopupVisible"
         HeaderText="Edit Contact"
         ShowFooter="true">
    <BodyTemplate Context="PopupContext">
        <div style="padding-top: 1rem; padding-bottom: 1rem">
            <DxFormLayout>
                <DxFormLayoutItem Caption="Contact Name:" ColSpanMd="12">
                    <Template>
                        <DxTextBox Text="Nancy Davolio" />
                    </Template>
                </DxFormLayoutItem>
                <DxFormLayoutItem Caption="Birth Date:" ColSpanMd="12">
                    <Template>
                        <DxDateEdit Date="DateTime.Now.AddYears(-30)" />
                    </Template>
                </DxFormLayoutItem>
                <DxFormLayoutItem Caption="Years Worked:" ColSpanMd="12">
                    <Template>
                        <DxSpinEdit Value="3" />
                    </Template>
                </DxFormLayoutItem>
                <DxFormLayoutItem Caption="Email:" ColSpanMd="12">
                    <Template>
                        <DxTextBox Text="NancyDavolio@sample.com" />
                    </Template>
                </DxFormLayoutItem>
            </DxFormLayout>
        </div>
    </BodyTemplate>
    <FooterContentTemplate>
        <DxButton RenderStyle="ButtonRenderStyle.Primary" Text="OK"
                  Click="@context.CloseCallback" />
    </FooterContentTemplate>
</DxPopup>

@code {
    bool PopupVisible { get; set; } = false;
}

Blazor Popup Templates

Run Demo: Popup - Customization

Alignment

The Popup is centered both horizontally and vertically on the screen. Use the HorizontalAlignment and VerticalAlignment properties to change the Popup position.

<div @onclick="@(() => PopupVisible = true)">
    <p>CLICK TO SHOW A POP-UP WINDOW</p>
</div>

<DxPopup @bind-Visible="@PopupVisible"
         HeaderText="Header"
         BodyText="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris sit amet metus vel
             nisi blandit tincidunt vel efficitur purus. Nunc nec turpis tempus, accumsan orci auctor,
             imperdiet mauris. Fusce id purus magna."
         HorizontalAlignment="HorizontalAlignment.Right"
         VerticalAlignment="VerticalAlignment.Bottom" />

@code {
    bool PopupVisible { get; set; } = false;
}

Run Demo: Popup - Alignment and Size

You can specify PositionX and PositionY properties to display the component at the specific coordinates. These properties have priority over HorizontalAlignment and VerticalAlignment.

Size

The Popup’s width is equal to 500px on desktops. On phones and tablets, the width adapts to the viewport width. The Popup’s height changes to fit the content.

Use the Width and Height properties to specify the Popup size in CSS units:

  • Specify the absolute width/height (for instance, Width="300px").
  • Specify the relative width/height (for instance, Width="50%").
  • Make the width/height fit the content (Width="auto").
<div @onclick="@(() => PopupVisible = true)">
    <p>CLICK TO SHOW A POP-UP WINDOW</p>
</div>

<DxPopup @bind-Visible="@PopupVisible"
         HeaderText="Header"
         BodyText="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris sit amet metus vel
             nisi blandit tincidunt vel efficitur purus. Nunc nec turpis tempus, accumsan orci auctor,
             imperdiet mauris. Fusce id purus magna."
         Width="400px"
         Height="200px" />

@code {
    bool PopupVisible { get; set; } = false;
}

Blazor Popup Custom Size

The MinWidth, MaxWidth, MinHeight, and MaxHeight properties allow you to define size constraints when the Popup automatically adapts to its content.

<div @onclick="@(() => PopupVisible = true)">
    <p>CLICK TO SHOW A POP-UP WINDOW</p>
</div>

<DxPopup @bind-Visible="@PopupVisible"
         HeaderText="Header"
         BodyText="@DynamicText"
         Width="auto"
         MinWidth="300px"
         MaxWidth="600px" />

@code {
    bool PopupVisible { get; set; } = false;
    string DynamicText { get; set; } // Get text from an external source.
}

When the Popup content does not fit the window’s size, this content is displayed over the window’s boundaries. Set the Scrollable property to true to show scrollbars and display all content inside the window’s boundaries.

Run Demo: Popup - Alignment and Size

Set the AllowResize property to true to allow users to change the component size at runtime.

<div @onclick="@(() => PopupVisible = true)">
    <p>CLICK TO SHOW A POP-UP WINDOW</p>
</div>

<DxPopup @bind-Visible="@PopupVisible"
         HeaderText="Header"
         BodyText="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris sit amet metus vel
                   nisi blandit tincidunt vel efficitur purus. Nunc nec turpis tempus, accumsan orci auctor,
                   imperdiet mauris. Fusce id purus magna."
         AllowResize="true"
         ApplyBackgroundShading="false">
</DxPopup>

@code {
    bool PopupVisible { get; set; } = false;
}

Resize the component

Run Demo: Resizing

Respond to Show and Close Actions

Handle the following events to process show and close actions:

  • Showing - Fires before the Popup is displayed and allows you to cancel this action.
  • Shown - Fires after the Popup is displayed.
  • Closing - Fires before the Popup is closed and allows you to cancel this action.
  • Closed - Fires after the Popup is closed.

In the following example, neither the Close button in the header nor the custom OK button closes the Popup until a user enables the checkbox in the footer.

Blazor Popup Close Events

<div @onclick="@(() => EulaVisible = true)">
    <p>CLICK TO SHOW A POP-UP WINDOW</p>
</div>

<DxPopup @bind-Visible="@EulaVisible"
         ShowFooter="true"
         HeaderText="DevExpress EULA"
         Closing="EulaPopupClosing"
         Closed="EulaPopupClosed">
    <BodyContentTemplate>
        <p>
            The terms of our license are fully outlined/described in the Developer Express Inc End User
            License Agreement (EULA) included with our product installations. Before you can install and use
            a Developer Express Inc product, you must read, understand and accept the terms/conditions of
            our EULAs. <a target="" _blank"" rel="" noopener noreferrer"" href=""
                          https: //www.devexpress.com/support/eulas/"">More info...</a>
        </p>
    </BodyContentTemplate>
    <FooterContentTemplate Context="Context">
        <DxCheckBox style="margin-left: 0; margin-right: auto;" @bind-Checked="@EulaAccepted">
            I accept the terms of the EULA
        </DxCheckBox>
        <DxButton RenderStyle="ButtonRenderStyle.Primary" Text="OK" Click="Context.CloseCallback" />
    </FooterContentTemplate>
</DxPopup>
@code {
    bool EulaAccepted { get; set; }
    bool EulaVisible { get; set; }

    void EulaPopupClosed(PopupClosedEventArgs args) {
        EulaAccepted = false;
    }
    void EulaPopupClosing(PopupClosingEventArgs args) {
        args.Cancel = !EulaAccepted;
    }
}

Run Demo: Popup - Response to Show and Close Actions

Multiple Popups

You can show multiple Popups simultaneously. Their Z-indices are calculated based on the display order. To change a Popup’s z-index, specify the ZIndex property.

The following example creates a Popup that users can close only after they enable the checkbox. Another Popup appears if users do not enable the checkbox.

Blazor Popup Multiple Windows

<div @onclick="@(() => EulaVisible = true)">
    <p>CLICK TO SHOW A POP-UP WINDOW</p>
</div>

<DxPopup @bind-Visible="@EulaVisible"
         ShowFooter="true"
         HeaderText="DevExpress EULA"
         Closing="EulaPopupClosing"
         Closed="EulaPopupClosed">
    <BodyContentTemplate>
        <p>
            The terms of our license are fully outlined/described in the Developer Express Inc End User
            License Agreement (EULA) included with our product installations. Before you can install and use
            a Developer Express Inc product, you must read, understand and accept the terms/conditions of
            our EULAs. <a target="" _blank"" rel="" noopener noreferrer"" href=""
                          https: //www.devexpress.com/support/eulas/"">More info...</a>
        </p>
    </BodyContentTemplate>
    <FooterContentTemplate Context="Context">
        <DxCheckBox style="margin-left: 0; margin-right: auto;" @bind-Checked="@EulaAccepted">
            I accept the terms of the EULA
        </DxCheckBox>
        <DxButton RenderStyle="ButtonRenderStyle.Primary" Text="OK" Click="Context.CloseCallback" />
    </FooterContentTemplate>
</DxPopup>
<DxPopup @bind-Visible="@MessageBoxVisible"
         ShowFooter="true"
         HeaderText="DevExpress EULA"
         BodyText="You must read and accept the terms of the EULA to continue.">
    <FooterContentTemplate Context="Context">
        <DxButton RenderStyle="ButtonRenderStyle.Primary" Text="OK" Click="Context.CloseCallback" />
    </FooterContentTemplate>
</DxPopup>
@code {
    bool EulaAccepted { get; set; }
    bool EulaVisible { get; set; }
    bool MessageBoxVisible { get; set; }

    void EulaPopupClosed() {
        EulaAccepted = false;
    }
    void EulaPopupClosing(PopupClosingEventArgs args) {
        if (!EulaAccepted) {
            args.Cancel = true;
            MessageBoxVisible = true;
        }
    }
}

Run Demo: Popup - Response to Show and Close Actions

Troubleshooting

If a Blazor application throws unexpected exceptions, refer to the following help topic: Troubleshooting.

See Also