Skip to main content

DxDropDown Class

A DropDown component.

Namespace: DevExpress.Blazor

Assembly: DevExpress.Blazor.v22.2.dll

NuGet Package: DevExpress.Blazor

Declaration

public class DxDropDown :
    DxSizableComponentBase,
    IPopupEventInfo,
    ISizableComponent,
    IParentPopupBranchInfo,
    IAsyncDisposable

Remarks

The DevExpress DropDown for Blazor (<DxDropDown>) allows you to create a drop-down window in your application.

Blazor DropDown Overview

Run Demo

Add a DropDown to a Project

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

Show and Close a DropDown

Implement two-way binding for the IsOpen property to show the DropDown in code.

<DxButton Id="showDDbutton" Click="() => IsOpen = true">Show DropDown</DxButton>
<DxDropDown @bind-IsOpen="@IsOpen"
            Width="400"
            BodyText="Lorem ipsum dolor sit amet, consectetuer adipiscing elit. 
              Maecenas porttitor congue massa.">
</DxDropDown>
@code {
    bool IsOpen { get; set; } = false;
}

You can call the ShowAsync and CloseAsync methods to show and close a drop-down window asynchronously.

<DxButton Text="Show" Click="ShowDropDown" />
<DxButton Text="Close" Click="CloseDropDown" />
<DxDropDown @ref="dropDown"
            Width="400"
            BodyText="Lorem ipsum dolor sit amet, consectetuer adipiscing elit. 
              Maecenas porttitor congue massa.">
</DxDropDown>
@code {
    DxDropDown dropDown { get; set; }
    async Task ShowDropDown(MouseEventArgs args) {
        await dropDown.ShowAsync();
    }
    async Task CloseDropDown(MouseEventArgs args) {
        await dropDown.CloseAsync();
    }
}

User Capabilities

Users can close the DropDown in the following ways:

  • Press Escape.
  • Click outside the DropDown’s boundaries. Set the CloseOnOutsideClick property to false to disable this option.

Respond to Show and Close Actions

Handle the following events to process show and close actions:

Showing
Fires before the drop-down window is displayed.
Shown
Fires after the drop-down window is displayed.
Closing
Fires before the drop-down window is closed.
Closed
Fires after the drop-down window is closed.

Content and Appearance

The drop-down window consists of the header, body, and footer elements. The header and footer are initially hidden. Set the HeaderVisible and FooterVisible properties to true to display these elements.

Each element can display text, a template for the text content, or a template for the entire element.

Display Text

Use the following properties to specify text displayed in the DropDown elements: HeaderText, BodyText, and FooterText.

<DxButton Id="showDDbutton" Click="() => IsOpen = true">Show DropDown</DxButton>
<DxDropDown @bind-IsOpen="@IsOpen"
            Width="400"
            HeaderVisible="true"
            FooterVisible="true"
            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."
            FooterText="Footer">
</DxDropDown>
@code {
    bool IsOpen { get; set; } = false;

}

Blazor DropDown Text Properties

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

Display Custom Content (Text Template)

Use the following properties to display any UI render fragment in the DropDown elements: HeaderTextTemplate, BodyTextTemplate, and FooterTextTemplate. A render fragment can include formatted text, images, another component, and so on. These templates affect the text area only, so the predefined content alignment and paddings apply.

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.

Run Demo: DropDown - Customization

<DxButton Id="showDDbutton" Click="() => IsOpen = true">Show DropDown</DxButton>
<DxDropDown @bind-IsOpen="@IsOpen"
            HeaderVisible="true"
            FooterVisible="true"
            Width="400"
            BodyText="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris sit amet metus vel
             nisi blandit tincidunt vel efficitur purus.">
    <HeaderTextTemplate>
        <div style="color: rgb(95,54,141); padding-left: 10px; font-size: 20px">
            Information
        </div>
    </HeaderTextTemplate>
    <FooterTextTemplate>
        <DxButton RenderStyle="ButtonRenderStyle.Primary" Text="OK" Click="@context.CloseCallback" />
    </FooterTextTemplate>
</DxDropDown>

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

Blazor DropDown Header and Footer Templates

Customize Entire Elements (Template)

Specify the HeaderTemplate, BodyTemplate, and FooterTemplate properties to define the content and appearance of DropDown elements. You can display any UI render fragment (for instance, formatted text, images, or another component).

These templates substitute all elements within the content, so the predefined appearance settings, content alignment and paddings, and the corresponding *Text, *CssClass, and *TextTemplate properties have no effect.

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

<DxButton Id="showDDbutton" Click="() => IsOpen = true">Show DropDown</DxButton>
<DxDropDown @bind-IsOpen="@IsOpen"
            Width="400"
            HeaderVisible="true"
            HeaderText="Edit Contact"
            FooterVisible="true">
    <BodyTemplate>
        <SampleEditForm />
    </BodyTemplate>
    <FooterTextTemplate>
        <DxButton RenderStyle="ButtonRenderStyle.Primary" Text="OK" Click="@context.CloseCallback" />
        <DxButton RenderStyle="ButtonRenderStyle.Secondary" Text="Cancel" Click="@context.CloseCallback" />
    </FooterTextTemplate>
</DxDropDown>

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

Blazor DropDown Body Templates

Use the Width and Height properties to specify the drop-down window’s size.

Run Demo: DropDown - Resizing

<DxButton Id="showDDbutton" Click="() => IsOpen = true">Show DropDown</DxButton>
<DxDropDown @bind-IsOpen="@IsOpen"
            Width="max(25vw, 300px)"
            Height="250"
            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.">
</DxDropDown>
@code {
    bool IsOpen { get; set; } = false;
}

Set the AllowResize property to true to allow users to resize the DropDown. Use the following properties to restrict changes to the component size: MinWidth, MaxWidth, MinHeight, MaxHeight.

<DxButton Id="showDDbutton" Click="() => IsOpen = true">Show DropDown</DxButton>
<DxDropDown @bind-IsOpen="@IsOpen"
            AllowResize="true"
            MinWidth="200"
            MaxWidth="400"
            MinHeight="200"
            MaxHeight="400"
            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.">
</DxDropDown>
@code {
    bool IsOpen { get; set; } = false;
}

The DropDown’s height changes to fit its content. When the height is restricted and the content exceeds the window’s boundaries, the control displays a vertical scroll bar. You can set the Scrollable property to false to disable the vertical scroll bar.

Use the PositionMode property to specify the DropDown position relative to a target element (PositionTarget) or to a Rectangle object (PositionRectangle). The HorizontalOffset and VerticalOffset properties set the component offset from the specified position.

Run Demo: DropDown - Position

<DxButton Id="showDDbtton" Click="() => IsOpen = true">Show a drop-down window</DxButton>
<DxDropDown PositionTarget="#showDDbtton"
            PositionMode="DropDownPositionMode.Bottom"
            HorizontalOffset="120"
            VerticalOffset="70"
            Width="210px"
            BodyText="Lorem ipsum dolor sit amet, consectetur adipiscing elit."
            @bind-IsOpen="@IsOpen">
</DxDropDown>

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

Blazor DropDown Offsets

The DropDown recalculates its position when certain page elements are changed (for instance, when the page is scrolled or resized). You can call the RepositionAsync method to force the DropDown to recalculate its position.

Position Restrictions

Use the RestrictionMode property to specify an element that restricts the DropDown position. The available options are as follows:

Viewport
The drop-down window position is restricted by the viewport.
Page
The drop-down window position is restricted by the page.
Rectangle
The drop-down window position is restricted by a rectangle’s boundaries (RestrictionRectangle).
TargetElement
The drop-down window position is restricted by a target element’s boundaries (RestrictionTarget).

The PositionMode and FitToRestriction properties determine how the DropDown behaves to fit the specified boundaries. When the component does not fit the restrictions, it can be hidden or closed, based on the CloseMode property value.

Run Demo: DropDown - Flipping

<OptionsContent>
    <OptionComboBox Label="Close mode:" CssClass="ow-100" Data="@CloseModeSource" @bind-Value="@CloseMode"/>
    <OptionCheckBox Label="Fit to container" @bind-Checked="FitToRestriction"/>
</OptionsContent>
<ChildContentWithParameters Context="Params">
    <div class="@(IsMobile ? "" : "card") flipping-overflow-container">
        <dxbl-demo-scrollable center-horizontally center-vertically id="flipping-target-container" class="flipping-overflow-content">
            <DxButton
                CssClass="flipping-button" Click="() => IsOpen = !IsOpen"
                RenderStyle="@ButtonRenderStyle.Secondary">SHOW A DROPDOWN</DxButton>
        </dxbl-demo-scrollable>
        <DxDropDown
            @bind-IsOpen="@IsOpen"
            CloseOnOutsideClick="false"
            PositionMode="DropDownPositionMode.Bottom"
            PositionTarget=".flipping-button"
            RestrictionTarget=".flipping-overflow-container"
            RestrictionMode="DropDownRestrictionMode.TargetElement"
            PreventCloseOnPositionTargetClick="true"
            CloseMode="@CloseMode"
            FitToRestriction="@FitToRestriction"
            SizeMode="Params.SizeMode"
            Width="240">
            <span style="font-size: 0.75rem">@Constants.ContentShort</span>
        </DxDropDown>
    </div>
</ChildContentWithParameters>

@code {
@* ... *@
    bool IsOpen { get; set; } = false;
    bool IsMobile { get; set; }
    bool FitToRestriction { get; set; } = true;
    DropDownCloseMode[] CloseModeSource { get; } = Enum.GetValues<DropDownCloseMode>();
    DropDownCloseMode CloseMode { get; set; } = DropDownCloseMode.Hide;
    @* ... *@
}

Troubleshooting

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

See Also