# ui/dropdown/utils

module

<a id="type-definitions">

## Type Definitions

<a id="typedef-ListDropdownButtonDefinition">

### `ListDropdownButtonDefinition`

<a id="typedef-ListDropdownGroupDefinition">

### `ListDropdownGroupDefinition`

<a id="typedef-ListDropdownItemDefinition">

### `ListDropdownItemDefinition`

<a id="typedef-ListDropdownSeparatorDefinition">

### `ListDropdownSeparatorDefinition`

<a id="functions">

## Functions

<a id="function-addListToDropdown">

### `addListToDropdown( dropdownView, itemsOrCallback, options = { options.ariaLabel?, options.role? } ) → void`

Adds an instance of [`ListView`](module_ui_list_listview-ListView.md) to a dropdown.

```typescript
const items = new Collection<ListDropdownItemDefinition>();

items.add( {
	type: 'button',
	model: new Model( {
		withText: true,
		label: 'First item',
		labelStyle: 'color: red'
	} )
} );

items.add( {
	 type: 'button',
	 model: new Model( {
		withText: true,
		label: 'Second item',
		labelStyle: 'color: green',
		class: 'foo'
	} )
} );

const dropdown = createDropdown( locale );

addListToDropdown( dropdown, items );

// Will render a dropdown with a list in the panel containing two items.
dropdown.render()
document.body.appendChild( dropdown.element );
```

The `items` collection passed to this methods controls the presence and attributes of respective [list items](module_ui_list_listitemview-ListItemView.md).

**Note:** To improve the accessibility, when a list is added to the dropdown using this helper the dropdown will automatically attempt to focus the first active item (a host to a [`ButtonView`](module_ui_button_buttonview-ButtonView.md) with [`isOn`](module_ui_button_buttonview-ButtonView.md#member-isOn) set `true`) or the very first item when none are active.

**Note:** List view will be created on first open of the dropdown.

See [`createDropdown`](#function-createDropdown) and [`List`](module_list_list-List.md).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-ui/src/dropdown/utils.ts#L416)

#### Parameters

* `dropdownView: DropdownView`

  A dropdown instance to which `ListVIew` will be added.

* `itemsOrCallback: Collection<ListDropdownItemDefinition> | () => Collection<ListDropdownItemDefinition>`

  A collection of the list item definitions or a callback returning a list item definitions to populate the list.

* `options: object`

  Properties

  * `options.ariaLabel?: string`

    Label used by assistive technologies to describe list element.

  * `options.role?: string`

    Will be reflected by the `role` DOM attribute in `ListVIew` and used by assistive technologies.

  Defaults to `{}`

#### Returns

* `void`

<a id="function-addMenuToDropdown">

### `addMenuToDropdown( dropdownView, body, definition, options = { options.ariaLabel? } ) → void`

Adds a menu UI component to a dropdown and sets all common behaviors and interactions between the dropdown and the menu.

Use this helper to create multi-level dropdown menus that are displayed in a toolbar.

Internally, it creates an instance of [`DropdownMenuRootListView`](module_ui_dropdown_menu_dropdownmenurootlistview-DropdownMenuRootListView.md).

Example:

```typescript
const definitions = [
	{
		id: 'menu_1',
		menu: 'Menu 1',
		children: [
			{
				id: 'menu_1_a',
				label: 'Item A'
			},
			{
				id: 'menu_1_b',
				label: 'Item B'
			}
		]
	},
	{
		id: 'top_a',
		label: 'Top Item A'
	},
	{
		id: 'top_b',
		label: 'Top Item B'
	}
];

const dropdownView = createDropdown( editor.locale );

addMenuToDropdown( dropdownView, editor.ui.view.body, definitions );
```

After using this helper, the `dropdown` will fire [`execute`](module_ui_dropdown_dropdownview-DropdownViewEvent.md) event when a nested menu button is pressed.

The helper will make sure that the `dropdownMenuRootListView` is lazy loaded, i.e., the menu component structure will be initialized and rendered only after the `dropdown` is opened for the first time.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-ui/src/dropdown/utils.ts#L191)

#### Parameters

* `dropdownView: DropdownView`

  A dropdown instance to which the menu component will be added.

* `body: BodyCollection`

  Body collection to which floating menu panels will be added.

* `definition: DropdownMenuDefinition`

  The menu component definition.

* `options: object`

  Properties

  * `options.ariaLabel?: string`

    Label used by assistive technologies to describe the top-level menu.

  Defaults to `{}`

#### Returns

* `void`

<a id="function-addToolbarToDropdown">

### `addToolbarToDropdown( dropdownView, buttonsOrCallback, options = { options.ariaLabel?, options.class?, options.enableActiveItemFocusOnDropdownOpen?, options.isCompact?, options.isVertical?, options.maxWidth? } ) → void`

Adds an instance of [`ToolbarView`](module_ui_toolbar_toolbarview-ToolbarView.md) to a dropdown.

```typescript
const buttonsCreator = () => {
	const buttons = [];

	// Either create a new ButtonView instance or create existing.
	buttons.push( new ButtonView() );
	buttons.push( editor.ui.componentFactory.create( 'someButton' ) );
};

const dropdown = createDropdown( locale );

addToolbarToDropdown( dropdown, buttonsCreator, { isVertical: true } );

// Will render a vertical button dropdown labeled "A button dropdown"
// with a button group in the panel containing two buttons.
// Buttons inside the dropdown will be created on first dropdown panel open.
dropdown.render()
document.body.appendChild( dropdown.element );
```

**Note:** To improve the accessibility, you can tell the dropdown to focus the first active button of the toolbar when the dropdown [gets open](module_ui_dropdown_dropdownview-DropdownView.md#member-isOpen). See the documentation of `options` to learn more.

**Note:** Toolbar view will be created on first open of the dropdown.

See [`createDropdown`](#function-createDropdown) and [`ToolbarView`](module_ui_toolbar_toolbarview-ToolbarView.md).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-ui/src/dropdown/utils.ts#L283)

#### Parameters

* `dropdownView: DropdownView`

  A dropdown instance to which `ToolbarView` will be added.

* `buttonsOrCallback: ViewCollection<View<HTMLElement>> | Array<View<HTMLElement>> | () => ( ViewCollection<View<HTMLElement>> | Array<View<HTMLElement>> )`

* `options: object`

  Properties

  * `options.ariaLabel?: string`

    Label used by assistive technologies to describe toolbar element.

  * `options.class?: string`

    An additional CSS class added to the toolbar element.

  * `options.enableActiveItemFocusOnDropdownOpen?: boolean`

    When set `true`, the focus will automatically move to the first active [item](module_ui_toolbar_toolbarview-ToolbarView.md#member-items) of the toolbar upon [opening](module_ui_dropdown_dropdownview-DropdownView.md#member-isOpen) the dropdown. Active items are those with the `isOn` property set `true` (for instance [buttons](module_ui_button_buttonview-ButtonView.md)). If no active items is found, the toolbar will be focused as a whole resulting in the focus moving to its first focusable item (default behavior of [`DropdownView`](module_ui_dropdown_dropdownview-DropdownView.md)).

  * `options.isCompact?: boolean`

    When set true, makes the toolbar look compact with toolbar element.

  * `options.isVertical?: boolean`

    Controls the orientation of toolbar items.

  * `options.maxWidth?: string`

    The maximum width of the toolbar element. Details: [`maxWidth`](module_ui_toolbar_toolbarview-ToolbarView.md#member-maxWidth).

  Defaults to `{}`

#### Returns

* `void`

<a id="function-createDropdown">

### `createDropdown( locale, ButtonClassOrInstance ) → DropdownView`

A helper for creating dropdowns. It creates an instance of a [dropdown](module_ui_dropdown_dropdownview-DropdownView.md), with a [button](module_ui_dropdown_button_dropdownbutton-DropdownButton.md), [panel](module_ui_dropdown_dropdownpanelview-DropdownPanelView.md) and all standard dropdown's behaviors.

#### Creating dropdowns

By default, the default [`DropdownButtonView`](module_ui_dropdown_button_dropdownbuttonview-DropdownButtonView.md) class is used as definition of the button:

```typescript
const dropdown = createDropdown( model );

// Configure dropdown's button properties:
dropdown.buttonView.set( {
	label: 'A dropdown',
	withText: true
} );

dropdown.render();

// Will render a dropdown labeled "A dropdown" with an empty panel.
document.body.appendChild( dropdown.element );
```

You can also provide other button views (they need to implement the [`DropdownButton`](module_ui_dropdown_button_dropdownbutton-DropdownButton.md) interface). For instance, you can use [`SplitButtonView`](module_ui_dropdown_button_splitbuttonview-SplitButtonView.md) to create a dropdown with a split button.

```typescript
const dropdown = createDropdown( locale, SplitButtonView );

// Configure dropdown's button properties:
dropdown.buttonView.set( {
	label: 'A dropdown',
	withText: true
} );

dropdown.buttonView.on( 'execute', () => {
	// Add the behavior of the "action part" of the split button.
	// Split button consists of the "action part" and "arrow part".
	// The arrow opens the dropdown while the action part can have some other behavior.
} );

dropdown.render();

// Will render a dropdown labeled "A dropdown" with an empty panel.
document.body.appendChild( dropdown.element );
```

#### Adding content to the dropdown's panel

The content of the panel can be inserted directly into the `dropdown.panelView.element`:

```typescript
dropdown.panelView.element.textContent = 'Content of the panel';
```

However, most of the time you will want to add there either a [list of options](module_ui_list_listview-ListView.md) or a list of buttons (i.e. a [toolbar](module_ui_toolbar_toolbarview-ToolbarView.md)). To simplify the task, you can use, respectively, [`addListToDropdown`](#function-addListToDropdown) or [`addToolbarToDropdown`](#function-addToolbarToDropdown) utils.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-ui/src/dropdown/utils.ts#L117)

#### Parameters

* `locale: Locale | undefined`

  The locale instance.

* `ButtonClassOrInstance: DropdownButton & View<HTMLElement> & object | new ( locale: Locale ) => DropdownButton & View<HTMLElement> & object`

  The dropdown button view class. Needs to implement the [`DropdownButton`](module_ui_dropdown_button_dropdownbutton-DropdownButton.md) interface.

  Defaults to `DropdownButtonView`

#### Returns

* `DropdownView`

  The dropdown view instance.

<a id="function-focusChildOnDropdownOpen">

### `focusChildOnDropdownOpen( dropdownView, childSelectorCallback ) → void`

A helper to be used on an existing [`DropdownView`](module_ui_dropdown_dropdownview-DropdownView.md) that focuses a specific child in DOM when the dropdown [gets open](module_ui_dropdown_dropdownview-DropdownView.md#member-isOpen).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-ui/src/dropdown/utils.ts#L479)

#### Parameters

* `dropdownView: DropdownView`

  A dropdown instance to which the focus behavior will be added.

* `childSelectorCallback: () => ( View<HTMLElement> | FalsyValue )`

  A callback executed when the dropdown gets open. It should return a [`View`](module_ui_view-View.md) instance (child of [`panelView`](module_ui_dropdown_dropdownview-DropdownView.md#member-panelView)) that will get focused or a falsy value. If falsy value is returned, a default behavior of the dropdown will engage focusing the first focusable child in the [`panelView`](module_ui_dropdown_dropdownview-DropdownView.md#member-panelView).

#### Returns

* `void`

---

Full index of the CKEditor 5 API reference: [llms.txt](llms.txt)