Skip to main content
All docs
V25.1
  • DxWindow Class

    A non-modal window with custom content.

    Namespace: DevExpress.Blazor

    Assembly: DevExpress.Blazor.v25.1.dll

    NuGet Package: DevExpress.Blazor

    Declaration

    public class DxWindow :
        DxComponentBase,
        IPopupEventInfo,
        IParentPopupBranchInfo,
        IPopupLayer,
        IAsyncDisposable

    Remarks

    The DevExpress Window for Blazor allows you to show a non-modal window with custom content. You can use it to display additional information or task progress, implement search dialogs, gather information from users, or ask for confirmation.

    When the window appears it captures input focus, but users can still interact with the rest of page.

    Blazor Window

    Run Demo: Window - Overview

    Add a Window to a Project

    Follow the steps below to add the Window 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 <DxWindow></DxWindow> markup to a .razor file.
    3. Write code that manages the Window’s visibility.
    4. Define the Window’s content and appearance.
    5. Configure other options (see the sections below).

    API Reference

    Refer to the following list for the component API reference: DxWindow Members.

    Static Render Mode Specifics

    Blazor Window does not support static render mode. Enable interactivity to use the component in your application. Refer to the following topic for more details: Enable Interactive Render Mode.

    Show and Close a Window

    Implement two-way binding for the Visible property. Change this property value in code to show or hide the Window. The component updates this property when a user closes the Window.

    <DxButton RenderStyle="ButtonRenderStyle.Secondary" 
              Click="() => WindowVisible = !WindowVisible">SHOW A WINDOW</DxButton>
    <DxWindow @bind-Visible=WindowVisible
              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="max(25vw, 250px)">
    </DxWindow>
    
    @code {
        bool WindowVisible { get; set; } = false;
    }
    

    Run Demo: Window - Overview

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

    To show the Window at the specified position, use the ShowAtAsync method overloads:

    ShowAtAsync(ElementReference, CancellationToken)
    Asynchronously shows the Window over the element specified by ElementReference.
    ShowAtAsync(Double, Double, CancellationToken)
    Asynchronously shows the Window at the specified coordinates.
    ShowAtAsync(Point, CancellationToken)
    Asynchronously shows the Window at the specified point.
    ShowAtAsync(String, CancellationToken)
    Asynchronously shows the Window over the element specified by a selector.
    <DxButton RenderStyle="ButtonRenderStyle.Secondary"
              Click="OnShowAtPositionClick">SHOW A WINDOW</DxButton>
    
    <DxWindow @ref=Window 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="max(25vw, 250px)"
              >
    </DxWindow>
    
    @code {
        DxWindow Window;
    
        async Task OnShowAtPositionClick(MouseEventArgs args) {
            await Window.ShowAtAsync(args.ClientX, args.ClientY);
        }
    }
    

    Run Demo: Window - Show Options

    All options mentioned above allow you to open multiple Windows on a page. Users can switch between windows and interact with associated content as necessary. When a window is focused, it overlaps other visible windows.

    Run Demo: Multiple Windows

    Respond to Show and Close Actions

    Handle the following events to process show and close actions:

    Showing
    Fires before the Window is displayed.
    Shown
    Fires after the Window is displayed.
    Closing
    Fires before the Window is closed.
    Closed
    Fires after the Window is closed.

    User Capabilities

    Users can close a Window in the following ways:

    • Click the Close button. Set the ShowCloseButton to true to show this button.
    • Press Escape. You can set the CloseOnEscape property to false to disable this capability.

    Content and Appearance

    The window consists of header, body, and footer. The footer is initially hidden. You can set the ShowFooter property to true to display the footer.

    Display Text

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

    <DxButton RenderStyle="ButtonRenderStyle.Secondary" 
              Click="() => WindowVisible = !WindowVisible">SHOW A WINDOW</DxButton>
    <DxWindow @bind-Visible="@WindowVisible"
              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."
              ShowFooter="true"
              FooterText="Footer"
              Width="max(25vw, 250px)">
    </DxWindow>
    
    @code {
        bool WindowVisible { get; set; } = false;
    }
    

    Blazor Window Footer

    Run Demo: Window - Overview

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

    Display Custom Content

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

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

    Each template has the context parameter. You can use the parameter’s CloseCallback property to implement a custom close button.

    <DxButton RenderStyle="ButtonRenderStyle.Secondary" 
              Click="() => WindowVisible = !WindowVisible">SHOW A WINDOW</DxButton>
    <DxWindow @bind-Visible=WindowVisible
              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="max(25vw, 250px)"
              BodyCssClass="body-style">
        <HeaderContentTemplate>
            <DxButton Text="X" Click="@context.CloseCallback" />
        </HeaderContentTemplate>
    </DxWindow>
    
    @code {
        bool WindowVisible { get; set; } = false;
    }
    

    Blazor Window - Header Text Template

    Customize Entire Elements

    Specify HeaderTemplate, BodyTemplate, and FooterTemplate properties to define the content and appearance of Window elements. 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 has the context parameter. You can use the parameter’s CloseCallback property to implement a custom close button.

    Window Size

    Use the Width and Height properties to specify the Window 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").
    <DxButton RenderStyle="ButtonRenderStyle.Secondary" 
              Click="() => WindowVisible = !WindowVisible">SHOW A WINDOW</DxButton>
    <DxWindow @bind-Visible=WindowVisible
              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="220"
              Height="80">
    </DxWindow>
    
    @code {
        bool WindowVisible { get; set; } = false;
    }
    

    When the Window 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 a vertical scrollbar and display all content inside the window’s boundaries.

    Resize Window

    Set the AllowResize property to true to allow users to resize the Window.

    Handle the following events to process resize actions:

    <DxButton RenderStyle="ButtonRenderStyle.Secondary" 
              Click="() => windowVisible = !windowVisible">SHOW A WINDOW</DxButton>
    <DxWindow @bind-Visible=windowVisible
              AllowResize=true
              ResizeCompleted="OnWindowResizeCompleted"
              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="@width"
              Height="@height">
    </DxWindow>
    
    @code {
        string width = "200px", height = "100px";
        bool windowVisible;
        void OnWindowResizeCompleted(WindowResizeCompletedEventArgs args) {
            (width, height) = ($"{args.Size.Width}px", $"{args.Size.Height}px");
        }
    }
    

    Run Demo: Window - Resizing

    You can use the following properties to restrict changes to the component size: MinWidth, MaxWidth, MinHeight, and MaxHeight.

    Window Position

    You can use the following properties to set the Window’s position:

    <DxButton RenderStyle="ButtonRenderStyle.Secondary" 
              Click="() => WindowVisible = !WindowVisible">SHOW A WINDOW</DxButton>
    <DxWindow @bind-Visible=WindowVisible
              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="max(25vw, 250px)"
              HorizontalAlignment="HorizontalAlignment.Center"
              VerticalAlignment="VerticalAlignment.Bottom">
    </DxWindow>
    
    @code {
        bool WindowVisible { get; set; } = false;
    }
    

    Drag Window

    Set the AllowDrag property to true to allow users to drag the Window to a new position.

    Handle the following events to process drag actions:

    <div class="d-flex justify-content-center p-3" @ref=@popupTarget>
        <DxButton RenderStyle="ButtonRenderStyle.Secondary" Click="@TogglePopupVisibilityAsync">@GetButtonText()</DxButton>
    </div>
    <DxWindow AllowDrag=true
              AllowDragByHeaderOnly="allowDragByHeaderOnly"
              @ref=@windowRef
              DragCompleted="OnWindowDragCompleted"
              ShowCloseButton="true"
              HeaderText="Window" BodyText="@Constants.Text"
              Width="max(25vw, 250px)"
              SizeMode="Params.SizeMode"
              @bind-Visible="windowVisible">
    </DxWindow>
    @code {
    int? positionX, positionY;
    bool windowVisible;
    bool allowDragByHeaderOnly = true;
    DxWindow windowRef;
    ElementReference popupTarget;
    async Task OnWindowDragCompleted(WindowDragCompletedEventArgs args) {
        (positionX, positionY) = (args.End.X, args.End.Y);
        await SavePositionToLocalStorageAsync(args.End);
    }
    string GetButtonText() => !windowVisible ? "SHOW A WINDOW" : "CLOSE A WINDOW";
    }
    

    Run Demo: Window - Dragging

    Keyboard Navigation

    The DevExpress Blazor Window component supports keyboard shortcuts that allow users to navigate through windows. Keyboard navigation is implemented on the client and server.

    Note

    Keyboard support allows users who cannot use a mouse or rely on assistive technologies (like screen readers or switch devices) to interact with application content. Refer to the Accessibility help topic for information on other accessibility areas that we address.

    The following shortcut keys are available:

    Shortcut Keys Description
    Tab,
    Shift + Tab
    Moves focus to the next or previous focusable element inside window. After the first/last element, moves focus to the main page content.
    Esc If CloseOnEscape is set to true, closes the window.

    Accessibility Information

    The Window component is always assigned the dialog role. This informs assistive technologies that the component is separated from the rest of the page.

    Note

    The Windows’s role attribute cannot be changed.

    The window’s accessible name is taken from its header element through the aria-labelledby attribute. However, if you customize the header’s content area with the HeaderContentTemplate property, you must manually label the component. Pass the following ARIA attributes to the Window’s Attributes property:

    • aria-labelledby – References the ID of another element (usually the visible window title) that defines the accessible name. This is the preferred method.
    • aria-label – Specify a string value that is used as the accessible name. Use this when a window header element has no visible text, or when its text does not properly describe the window’s purpose.
    <DxWindow @bind-Visible="WindowVisible"
              aria-labelledby="my-custom-window-header">
        <HeaderContentTemplate>
            <h2 id="my-custom-window-header">Accessible Window</h2>
        </HeaderContentTemplate>
        <BodyContentTemplate>
            @* ... *@
        </BodyContentTemplate>
    </DxWindow>
    
    See Also