--- metadata: - name: generator content: Diplodoc Platform v5.39.1 alternate: - https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/control.ListBox.md - https://yandex.ru/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/control.ListBox.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/jsapi-v2-1/doc/en/llms.txt # control.ListBox Extends [ICollection](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICollection.md), [IControl](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IControl.md), [ICustomizable](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICustomizable.md). Class for creating a control in the form of a drop-down list. The standard drop-down list layout changes its appearance depending on the size of the map. If the map is wide enough, text can be displayed in the header of a drop-down list. If the map is small in size, only an icon is displayed. If a button has no icon, then only text will be displayed in all states, and vice versa. [Constructor](#constructor-summary) | [Fields](#properties-summary) | [Events](#events-summary) | [Methods](#methods-summary) ## Constructor {#constructor-summary} ```javascript control.ListBox([parameters]) ``` **Parameters:** #| || **Parameter** | **Default value** | **Description** || || [`parameters`](#param-parameters) | — | Type: Object Drop-down list parameters. || || [`parameters.data`](#param-parameters.data) | — | Type: Object Data. || || [`parameters.data.content`](#param-parameters.data.content) | — | Type: String List title. || || [`parameters.data.image`](#param-parameters.data.image) | — | Type: String URL of the button icon. The standard layout of a button is designed for the icon size 16x16 pixels. || || [`parameters.data.title`](#param-parameters.data.title) | — | Type: String Text of the popup hint that appears when the mouse cursor hovers over the list. || || [`parameters.items`](#param-parameters.items) | — | Type: [IControl](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IControl.md)[] Array of child elements of the list. || || [`parameters.options`](#param-parameters.options) | — | Type: Object Control options. || || [`parameters.options.adjustMapMargin`](#param-parameters.options.adjustMapMargin) | false | Type: Boolean Whether the control registers its size in the map margins manager [map.margin.Manager](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/map.margin.Manager.md). || || [`parameters.options.collapseOnBlur`](#param-parameters.options.collapseOnBlur) | true | Type: Boolean This flag enables to collapse the list when the button loses focus, such as when a user clicks on the document. || || [`parameters.options.expandOnClick`](#param-parameters.options.expandOnClick) | true | Type: Boolean Flag that allows automatically expanding/collapsing the list when clicked. || || [`parameters.options.float`](#param-parameters.options.float) | "right" | Type: String The side to which you want to align the control. Can take three values: "left", "right" or "none". If set to "left" or "right", the controls are arranged one by one, starting from the left or right edge of the map, respectively. If set to "none", the controls are positioned according to the values of the left, right, bottom and top options, relative to the boundaries of the map. See also the description of the position option. || || [`parameters.options.floatIndex`](#param-parameters.options.floatIndex) | 0 | Type: Number The priority of the control positioning. The element with highest priority is positioned closer to the map boundary that is specified in the float property. Does not work with float = "none". || || [`parameters.options.layout`](#param-parameters.options.layout) | — | Type: Function\|String Constructor of the control layout which implements the [ISelectableControlLayout](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ISelectableControlLayout.md) and [IGroupControlLayout](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IGroupControlLayout.md) interfaces or the layout key in the [layout.storage](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/layout.storage.md). The layout constructor is passed an object containing the fields: - control - Reference to the control. - options - Control options manager control.ListBox.options. - data - Control data manager [control.ListBox.data](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/control.ListBox.md#data). - state - Control state manager [control.ListBox.state](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/control.ListBox.md#state). The layout's outward appearance changes based on the control's data, state and options. The control, in turn, reacts to layout interface events and changes the values of fields for [control.ListBox.state](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/control.ListBox.md#state) depending on the commands received. || || [`parameters.options.maxWidth`](#param-parameters.options.maxWidth) | 90 | Type: Number\|Number[] The maximum width of the listbox in different states. If a number is specified, it is assumed that the button has the same maximum dimensions in all states. If an array is specified, it will be interpreted as the maximum width of the button in different states, from the lesser to the greater. The number of states is set in the instance of the class [control.Manager](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/control.Manager.md), which is usually a field of [Map.controls](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Map.md#controls), via the "states" option. By default, the controls have three states ['small', 'medium', 'large']. || || [`parameters.options.popupFloat`](#param-parameters.options.popupFloat) | — | Type: String The side to align the manager element's popup to. Takes two values: "left" and "right". By default, it is defined by the "float" option. || || [`parameters.options.position`](#param-parameters.options.position) | — | Type: Object Object describing the position of a control. If the position option is set, the float option value is automatically treated as "none". || || [`parameters.options.position.bottom`](#param-parameters.options.position.bottom) | 'auto' | Type: Number\|String Position relative to the bottom edge of the map. || || [`parameters.options.position.left`](#param-parameters.options.position.left) | 'auto' | Type: Number\|String Position relative to the left edge of the map. || || [`parameters.options.position.right`](#param-parameters.options.position.right) | 'auto' | Type: Number\|String Position relative to the right edge of the map. || || [`parameters.options.position.top`](#param-parameters.options.position.top) | 'auto' | Type: Number\|String Position relative to the top edge of the map. || || [`parameters.options.visible`](#param-parameters.options.visible) | true | Type: Boolean Indicates if the control is displayed. || || [`parameters.state`](#param-parameters.state) | — | Type: Object State of the drop-down list. || || [`parameters.state.expanded`](#param-parameters.state.expanded) | false | Type: Boolean Flags if the list is expanded. || |# **Examples:** **1.** ```javascript // Example 1. // Handling a click on list items. var cityList = new ymaps.control.ListBox({ data: { content: 'Select a city' }, items: [ new ymaps.control.ListBoxItem('Moscow'), new ymaps.control.ListBoxItem('Novosibirsk'), new ymaps.control.ListBoxItem({options: {type: 'separator'}}), new ymaps.control.ListBoxItem('New York'), ] }); cityList.get(0).events.add('click', function () { map.setCenter([55.752736, 37.606815]); }); cityList.get(1).events.add('click', function () { map.setCenter([55.026366, 82.907803]); }); cityList.get(3).events.add('click', function () { map.setCenter([40.695537, -73.97552]); }); map.controls.add(cityList, { floatIndex: 0 }); ``` **2.** ```javascript // Example 2. // Creating a custom list. // This example uses jQuery, downloaded from http://yandex.st/jquery/1.6.4/jquery.min.js // By default, the drop-down list reacts to the "click" event and automatically // changes its state to expanded or collapsed. var MyListBoxLayout = ymaps.templateLayoutFactory.createClass( '
{{ data.title }}
' + // This item will serve as a container for the child list items. '
' + '
', { build: function() { MyListBoxLayout.superclass.build.call(this); this.childContainerElement = $('#my-list-box').get(0); // Each time we rebuild, we will generate an event // that signals that the container for child elements has changed. // The event format is described in the IGroupControlLayout interface. this.events.fire('childcontainerchange', { newChildContainerElement: this.childContainerElement, oldChildContainerElement: null }); }, // Redefining the method that requires the IGroupControlLayout interface. getChildContainerElement: function () { return this.childContainerElement; } } ); // Creating a list and displaying the created layout via the options. var listBox = new ymaps.control.ListBox({options: {layout: MyListBoxLayout}}); ``` **3.** ```javascript // Example 3. // In this example, the ListBox control filters objects to show // on the map (multi-select is supported). // ObjectManager is used here for adding objects to the map. // Creating a drop-down list with 5 items. var listBoxItems = ['School', 'Pharmacy', 'Store', 'Hospital', 'Bar'] .map(function(title) { return new ymaps.control.ListBoxItem({ data: { content: title }, state: { selected: true } }); }); // Now creating the drop-down list with 5 items. var listBoxControl = new ymaps.control.ListBox({ data: { content: 'Filter', title: 'Filter' }, items: listBoxItems, state: { // Indicates that the list is expanded. expanded: true, filters: listBoxItems.reduce(function(filters, filter) { filters[filter.data.get('content')] = filter.isSelected(); return filters; }, {}) } }); map.controls.add(listBoxControl); // Adding tracking to the indicator to check if a list item is selected. listBoxControl.events.add(['select', 'deselect'], function(e) { var listBoxItem = e.get('target'); var filters = ymaps.util.extend({}, listBoxControl.state.get('filters')); filters[listBoxItem.data.get('content')] = listBoxItem.isSelected(); listBoxControl.state.set('filters', filters); }); // Tracking changes to the control.ListBox.state field. var filterMonitor = new ymaps.Monitor(listBoxControl.state); filterMonitor.add('filters', function(filters) { // Applying the filter to ObjectManager. objectManager.setFilter(getFilterFunction(filters)); }); function getFilterFunction(categories){ return function(obj){ var content = obj.properties.balloonContent; return categories[content] } } ``` ## Fields {#properties-summary} #| || **Name** | **Type** | **Description** || || [data](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/control.ListBox.md#data) | [data.Manager](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/data.Manager.md)| Drop-down list data. Names of fields that are available via the data.Manager.get method: - content - Title of the drop-down list. - title - Text of the popup hint that appears when the mouse cursor hovers over the list. || || [events](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IEventEmitter.md#events) | [IEventManager](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IEventManager.md)| Event manager. Inherited from [IEventEmitter](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IEventEmitter.md#events). || || [options](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IControl.md#options) | [IOptionManager](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IOptionManager.md)| Options manager. Inherited from [IControl](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IControl.md#options). || || [state](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/control.ListBox.md#state) | [data.Manager](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/data.Manager.md)| State of the drop-down list. Names of fields that are available via the data.Manager.get method: - expanded - Flag for whether the list is expanded. - size - The size that is currently set for the list. || |# ## Events {#events-summary} #| || **Name** | **Description** || || [add](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICollection.md#event-add)| A child object was added. Inherited from [ICollection](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICollection.md#event-add). || || [click](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/control.ListBox.md#event-click)| Clicking the list title. Instance of the [Event](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md) class. || || [collapse](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/control.ListBox.md#event-collapse)| The list is closed. Instance of the [Event](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md) class. || || [expand](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/control.ListBox.md#event-expand)| The list is open. Instance of the [Event](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md) class. || || [optionschange](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICustomizable.md#event-optionschange)| Change to the object options. Inherited from [ICustomizable](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICustomizable.md#event-optionschange). || || [parentchange](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChild.md#event-parentchange)| The parent object reference changed. Data fields: - oldParent - Old parent. - newParent - New parent. Inherited from [IChild](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChild.md#event-parentchange). || || [press](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/control.ListBox.md#event-press)| The event indicating that the button has been pressed. Unlike the click event, it is generated only if the state isEnabled == true. Instance of the [Event](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md) class. || || [remove](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICollection.md#event-remove)| A child object was deleted. Inherited from [ICollection](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICollection.md#event-remove). || |# ## Methods {#methods-summary} #| || **Name** | **Returns** | **Description** || || [add](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICollection.md#add)([object](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICollection.md#add-param-object)) | [ICollection](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICollection.md) | Adds a child object to the collection. Inherited from [ICollection](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICollection.md#add). || || [collapse](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/control.ListBox.md#collapse)() | [control.ListBox](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/control.ListBox.md) | Collapses the list. || || [expand](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/control.ListBox.md#expand)() | [control.ListBox](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/control.ListBox.md) | Expands the list. || || [getIterator](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICollection.md#getIterator)() | [IIterator](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IIterator.md) | Returns iterator for the collection. Inherited from [ICollection](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICollection.md#getIterator). || || [getMap](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/control.ListBox.md#getMap)() | [Map](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Map.md) | Returns reference to the map. || || [getParent](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IControl.md#getParent)() | [IControlParent](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IControlParent.md)\|null | Returns link to the parent object, or null if the parent element was not set. Inherited from [IControl](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IControl.md#getParent). || || [isExpanded](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/control.ListBox.md#isExpanded)() | Boolean | Returns a flag for whether the control is in the expanded state. || || [remove](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICollection.md#remove)([object](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICollection.md#remove-param-object)) | [ICollection](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICollection.md) | Removes a child object from the collection. Inherited from [ICollection](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICollection.md#remove). || || [setParent](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IControl.md#setParent)([parent](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IControl.md#setParent-param-parent)) | [IChildOnMap](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChildOnMap.md) | Sets the parent object. If the null value is passed, the manager element will only be deleted from the current parent object. Inherited from [IControl](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IControl.md#setParent). || |# ## Fields details {#field_detail} ### data {#data} ```javascript {data.Manager} data ``` Drop-down list data. Names of fields that are available via the data.Manager.get method: - content - Title of the drop-down list. - title - Text of the popup hint that appears when the mouse cursor hovers over the list. **Example:** ```javascript // Adding a drop-down list to the map and changing its hint // depending on whether the list is collapsed or expanded. // Creating a group of event listeners. var listBoxListener = listBox.events.group() .add('expand', function () { listBox.data.set('title', 'List is expanded'); }) .add('collapse', function () { listBox.data.set('title', 'List is collapsed'); }); map.controls.add(listBox, {float: 'none', top: 10, left: 10}); // ... map.controls.remove(listBox); // After deleting the item from the map, we delete the listeners. listBoxListener.removeAll(); ``` ### state {#state} ```javascript {data.Manager} state ``` State of the drop-down list. Names of fields that are available via the data.Manager.get method: - expanded - Flag for whether the list is expanded. - size - The size that is currently set for the list. **Example:** ```javascript // Creating and adding a list that is initially open. var listBox = new ymaps.control.ListBox(); listBox.state.set('expanded', true); map.controls.add(listBox); ``` ## Events details {#event_detail} ### click {#click} Clicking the list title. Instance of the [Event](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md) class. ### collapse {#collapse} The list is closed. Instance of the [Event](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md) class. ### expand {#expand} The list is open. Instance of the [Event](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md) class. ### press {#press} The event indicating that the button has been pressed. Unlike the click event, it is generated only if the state isEnabled == true. Instance of the [Event](https://yandex.ru/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Event.md) class. ## Methods details {#method_detail} ### collapse {#collapse} ```javascript {control.ListBox} collapse() ``` Collapses the list. **Returns** self-reference. ### expand {#expand} ```javascript {control.ListBox} expand() ``` Expands the list. **Returns** self-reference. ### getMap {#getMap} ```javascript {Map} getMap() ``` **Returns** reference to the map. ### isExpanded {#isExpanded} ```javascript {Boolean} isExpanded() ``` **Returns** a flag for whether the control is in the expanded state.