# Blazor DropDownButton Overview

The <a href = "https://www.telerik.com/blazor-ui/dropdownbutton" target="_blank">DropDownButton for Blazor</a> is a combination of a button and a dropdown. It provides a collection of related user actions in a compact interface. The DropDownButton allows users to click the primary button and open the popup to choose from a list of additional actions.

## DropDownButton vs. SplitButton

The DropDownButton and SplitButton components are similar. They both consist of a primary button and a dropdown element that holds additional action items. The major difference is the purpose of the primary button.

* [DropDownButton](https://www.telerik.com/blazor-ui/documentation/components/dropdownbutton/overview)—The main purpose of the primary button is to open the popup with additional actions. The primary button exposes a separate [`OnClick` event](https://www.telerik.com/blazor-ui/documentation/components/dropdownbutton/events), which can invoke a dedicated action. Clicking on the DropDownButton always opens the dropdown.

* [SplitButton](https://www.telerik.com/blazor-ui/documentation/components/splitbutton/overview)—The main element contains a primary button and a separate button for opening the dropdown. The purpose of the primary button is to [invoke a standalone action](https://www.telerik.com/blazor-ui/documentation/components/splitbutton/events#onclick). Clicking on it does not open the dropdown. To open the popup with the additional actions, the user has to click the dedicated button with `caret-alt-down` icon. It is possible to [switch the primary and dropdown actions programmatically](https://www.telerik.com/blazor-ui/documentation/knowledge-base/splitbutton-dynamic-primary-change-onclick).

## Creating Blazor DropDownButton

1. Add a `<TelerikDropDownButton>` tag.
2. (optional) Use the `Icon` parameter of the  `<TelerikDropDownButton>` tag to add an icon to the primary button.
3. (optional) Handle the `OnClick` event of the  `<TelerikDropDownButton>`.
4. Define the primary button content in a child `<DropDownButtonContent>` tag. The content can be plain text, HTML or even another component.
5. Add a child `<DropDownButtonItems>` tag. This will hold the actions rendered in the dropdown.
6. Add the desired `<DropDownButtonItem>` instances inside the `<DropDownButtonItems>` tag. Specify their content and icons and handle their `OnClick` events.

> caption Basic DropDownButton

<demo metaUrl="client/dropdownbutton/overview/basic/" height="300"></demo>

## Icons

The primary DropDownButton action and each secondary item in the dropdown can [display an icon or an image](https://www.telerik.com/blazor-ui/documentation/components/dropdownbutton/icons) for better looks and user experience.

## Appearance

The DropDownButton provides a [variety of settings to control its visual appearance](https://www.telerik.com/blazor-ui/documentation/components/dropdownbutton/appearance), for example, the colors, borders, and size. This spares the need to use custom CSS code.

> tip To learn more about the appearance, anatomy, and accessibility of the DropDownButton, visit the [Progress Design System Kit documentation](https://www.telerik.com/design-system/docs/components/dropdownbutton/)—an information portal offering rich component usage guidelines, descriptions of the available style variables, and globalization support details.

## Events

Each DropDownButton action [fires a separate `OnClick` event](https://www.telerik.com/blazor-ui/documentation/components/dropdownbutton/events) so that the application can react to user behavior.

## DropDownButton Parameters

The following table lists the DropDownButton parameters, except those related to [built-in styling](https://www.telerik.com/blazor-ui/documentation/components/dropdownbutton/appearance) and [icons](https://www.telerik.com/blazor-ui/documentation/components/dropdownbutton/icons). Also check the [DropDownButton API Reference](https://www.telerik.com/blazor-ui/documentation/api/telerik.blazor.components.telerikdropdownbutton) for a full list of properties, methods, and events.

<style>
    .article table {
        table-layout: auto;
        word-break: normal;
    }
</style>

| Parameter         | Type and Default Value | Description                                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AriaDescribedBy` | `string`               | Sets the `aria-describedby` attribute of the primary button element `<button class="k-button">`.                                                                                                                                                                                                                                                                                                                     |
| `AriaLabel`       | `string`               | Sets the `aria-label` attribute of the primary button element `<button class="k-button">`.                                                                                                                                                                                                                                                                                                                           |
| `AriaLabelledBy`  | `string`               | Sets the `aria-labelledby` attribute of the primary button element `<button class="k-button">`.                                                                                                                                                                                                                                                                                                                      |
| `Class`           | `string`               | Renders a custom CSS class to the main component element `<div class="k-dropdown-button">`. Use it to [override the theme styles](https://www.telerik.com/blazor-ui/documentation/styling-and-themes/override-theme-styles) and achieve a specific appearance if none of the [DropDownButton appearance settings](https://www.telerik.com/blazor-ui/documentation/components/dropdownbutton/appearance) can do this. |
| `Enabled`         | `bool`<br />(`true`)   | Defines whether the primary button is enabled.                                                                                                                                                                                                                                                                                                                                                                       |
| `Id`              | `string`               | Sets the `id` attribute of the primary button element `<button class="k-button">`.                                                                                                                                                                                                                                                                                                                                   |
| `ShowArrowButton` | `bool`                 | Sets the visibility of the Arrow button that displays the popup of the component.                                                                                                                                                                                                                                                                                                                                    |
| `TabIndex`        | `int`                  | Sets the `tabindex` attribute of the primary button element `<button class="k-button">`.                                                                                                                                                                                                                                                                                                                             |
| `Title`           | `string`               | Sets the `title` attribute of the primary button element `<button class="k-button">`.                                                                                                                                                                                                                                                                                                                                |

### Popup Settings

The DropDownButton exposes settings for its dropdown (popup). To configure the options, declare a  `<DropDownButtonPopupSettings>` tag inside a `<DropDownButtonSettings>` tag:

```RAZOR.skip-repl
<TelerikDropDownButton>
    <DropDownButtonSettings>
        <DropDownButtonPopupSettings Height="auto" MaxHeight="160px" />
    </DropDownButtonSettings>
</TelerikDropDownButton>
```

The DropDownButton provides the following popup settings:

<style>
    .article table {
        table-layout: auto;
        word-break: normal;
    }
</style>

| Parameter           | Type                 | Description                                                                                                                                                          |
| ------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AnimationDuration` | `int` <br /> (`300`) | Sets the dropdown animation duration in milliseconds.                                                                                                                |
| `Class`             | `string`             | Additional CSS class to customize the appearance of the popup.                                                                                                       |
| `Height`            | `string`             | The height of the popup. The default value is `"200px"`.                                                                                                             |
| `MinHeight`         | `string`             | The minimum height of the popup.                                                                                                                                     |
| `MinWidth`          | `string`             | The minimum width of the popup.                                                                                                                                      |
| `MaxHeight`         | `string`             | The maximum height of the popup.                                                                                                                                     |
| `MaxWidth`          | `string`             | The maximum width of the popup.                                                                                                                                      |
| `Width`             | `string`             | The width of the popup. If you don't specify a value, the dropdown width will match the anchor element width which can help with responsive layouts and 100% widths. |

The parameters that modify the popup dimensions (`Height`, `Width`, `MaxWidth`, etc.) expect [valid CSS values](https://www.telerik.com/blazor-ui/documentation/common-features/dimensions).

The `MinHeight` and `MaxHeight` have no effect if the `Height` is always within their range. The min and max values are useful only when the dropdown height is set to a relative unit or changes at runtime.

### Item Settings

The following table lists the `DropDownButtonItem` parameters, except those related to [icons](https://www.telerik.com/blazor-ui/documentation/components/dropdownbutton/icons).

| Parameter | Type and Default Value | Description                                                                                            |
| --------- | ---------------------- | ------------------------------------------------------------------------------------------------------ |
| `Class`   | `string`               | Renders a custom CSS class to the dropdown item's element, which is `<li class="k-item k-menu-item">`. |
| `Enabled` | `bool`<br />(`true`)   | Defines whether the item is enabled.                                                                   |

## DropDownButton Reference and Methods

The DropDownButton exposes a `FocusAsync` method that allows you to focus it programmatically. To use it, define a reference to the component instance with the `@ref` attribute. Consider the Blazor life cycle if you want to [focus the component on page load](https://www.telerik.com/blazor-ui/documentation/knowledge-base/inputs-set-focus#focus-on-page-load).

> caption Get a reference to the DropDownButton and execute methods

<demo metaUrl="client/dropdownbutton/overview/focus/" height="300"></demo>

## Next Steps

* [Add DropDownButton Icons](https://www.telerik.com/blazor-ui/documentation/components/dropdownbutton/icons)
* [Handle DropDownButton Events](https://www.telerik.com/blazor-ui/documentation/components/dropdownbutton/events)
* [Configure the DropDownButton appearance](https://www.telerik.com/blazor-ui/documentation/components/dropdownbutton/appearance)

## See Also

* [DropDownButton API](https://www.telerik.com/blazor-ui/documentation/api/telerik.blazor.components.telerikdropdownbutton)
* [Live Demo: DropDownButton](https://demos.telerik.com/blazor-ui/dropdownbutton/overview)
* [Live Demo: DropDownButton Items](https://demos.telerik.com/blazor-ui/dropdownbutton/items)
* [Hierarchical DropDownButton Items](https://www.telerik.com/blazor-ui/documentation/knowledge-base/dropdownbutton-nested-item-hierarchy)
