Documentation
Reference
2.1.38 (current version)
collection
interactivityModel
Interfaces

control.SearchControl

Extends IControl, ICustomizable.

The "Search on map" control. Allows you to process a user's search query and display the result in the panel and on the map.

Each search result represents a two-line block on the panel of a control. To generate the block, the "name" and "description" fields from the geocoding result object are used.

The key of the control in the storage. control.storage — "searchControl".

Constructor | Fields | Events | Methods

Constructor

control.SearchControl([parameters])

Parameters:

ParameterDefault valueDescription
parameters

Type: Object

Control parameters.

parameters.data

Type: Object

Object describing the data of a control.

parameters.options

Type: Object

Control options.

parameters.options.adjustMapMargin false

Type: Boolean

Whether the control registers its dimensions in the map margins manager map.margin.Manager.

parameters.options.boundedBy

Type: Number[][]

A rectangular area on the map, where the object being searched for is presumably located. For ranking, the objects located inside the specified area will receive higher priority.

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 200

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.formLayout 'islands#searchControlFormLayout'

Type: ILayout | String

The constructor of the form layout to search the layout of the default control or key in the layout.storage.

The layout constructor is passed an object containing the fields:

  • control - Reference to the control.
  • options - Control options manager control.SearchControl.options.
  • data - Control data manager control.SearchControl.data.
  • state - Control state manager control.SearchControl.state.
parameters.options.kind 'house'

Type: String

Type of toponym (only for reverse geocoding). List of acceptable values:

  • house - House or building.
  • street - Street.
  • metro - Subway station.
  • district - City district.
  • locality - City, town, village, etc.

parameters.options.layout 'islands#searchControlLayout'

Type: ISearchControlLayout | String

Control layout.

The layout constructor is passed an object containing the fields:

  • control - Reference to the control.
  • options - Control options manager control.SearchControl.options.
  • data - Control data manager control.SearchControl.data.
  • state - Control state manager control.SearchControl.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.SearchControl.state depending on the commands received.

parameters.options.maxWidth [30, 72, 290]

Type: Number | Number[]

The maximum width of the control in different states. If a number is specified, it is assumed that the control has the same maximum dimensions in all states. If an array is specified, it will be interpreted as the maximum width in different states from the lesser to the greater. The number of states is specified in the instance of the control.Manager class via the states option, which is usually represented by the Map.controls field. By default, the controls have three states ['small', 'medium', 'large'].

parameters.options.noCentering false

Type: Boolean

If false, the map center is automatically placed so that the object is entirely visible; if true, the map center is not changed when showing the found object. If noCentering = true and noPlacemark = true are set, no visible changes will occur on the map when search results are clicked.

parameters.options.noPlacemark false

Type: Boolean

If false, a placemark with an open balloon is automatically added to the center of the found object; if true, it is not. If noCentering = true and noPlacemark = true are set, no visible changes will occur on the map when search results are clicked. This option doesn't work with the yandex#search provider.

parameters.options.noPopup false

Type: Boolean

If true, the drop-down list of results is not shown; if false, it is shown.

parameters.options.noSelect false

Type: Boolean

If false, the search result will be automatically displayed in case it is the only object found; if true, the result will not be selected.

parameters.options.noSuggestPanel false

Type: Boolean

If true, the panel with the search suggestions is not shown; if false, it is shown.

parameters.options.placeholderContent

Type: String

Text of the hint, displayed in the input field of the control.

parameters.options.popupItemLayout 'islands#searchControlPopupItemLayout'

Type: ILayout | String

The constructor of the search result form layout in the drop-down list in the layout of the default control or key in the layout.storage.

The layout constructor is passed an object containing the fields:

  • control - Reference to the control.
  • options - Control options manager control.SearchControl.options.
  • data - Control data manager control.SearchControl.data.
  • state - Control state manager control.SearchControl.state.
parameters.options.popupLayout 'islands#searchControlPopupLayout'

Type: ILayout | String

The constructor of the layout of the drop-down list with search results in the default control layout or key in the layout.storage.

The layout constructor is passed an object containing the fields:

  • control - Reference to the control.
  • options - Control options manager control.SearchControl.options.
  • data - Control data manager control.SearchControl.data.
  • state - Control state manager control.SearchControl.state.
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 'auto'

Type: Number | String

Position relative to the bottom edge of the map.

parameters.options.position.left 'auto'

Type: Number | String

Position relative to the left edge of the map.

parameters.options.position.right 'auto'

Type: Number | String

Position relative to the right edge of the map.

parameters.options.position.top 'auto'

Type: Number | String

Position relative to the top edge of the map.

parameters.options.provider 'yandex#map'

Type: IGeocodeProvider | String

Geocoding provider. One of the standard providers can be used:

  • 'yandex#map' - Search for toponyms on the map.
  • 'yandex#search' - Search for toponyms and businesses. When searching for businesses, the following options don't work: "noPlacemark", "noCentering", "noSelect", "strictBounds", "kind". Moreover, if the "results" option is not specified for the control, the map, by default, cannot show more than 20 objects simultaneously.

parameters.options.searchCoordOrder 'latlong'

Type: String

Determines how to interpret the coordinates in the request. By default, coordinates will be processed as latitude-longitude. This option doesn't work with the yandex#search provider.

parameters.options.size 'auto'

Type: String

Defines the appearance of the control. Takes the following values:

  • 'small' — Always show the button with the icon.
  • 'medium' — Always show the button with text.
  • 'large' — Always show a full search form.
  • 'auto' — Automatically select the control size, depending on the amount of free space in the toolbar.

parameters.options.strictBounds

Type: Boolean

Search only inside the area defined by the "boundedBy" option. Objects that are outside of the specified area will not be in the output.

parameters.options.suppressYandexSearch false

Type: Boolean

Whether to hide the message offering to search on the Yandex portal if results were not found.

parameters.options.useMapBounds

Type: Boolean

Flag for taking into account the boundaries of the visible map area when searching. If true, the visible area that is calculated has higher priority than the area defined by boundedBy.

parameters.options.zoomMargin 0

Type: Number | Number[]

Represents the margins from the boundaries of the visible area of the map when displaying search results. The option works only if the value of noCentering is false. If a single number is set, it is applied to each side. If two numbers are set, they are the horizontal and vertical margins, respectively. If an array of four numbers is set, they are the top, right, bottom, and left margins. When the option "useMapMargin" is enabled, the "zoomMargin" value is combined with the values that were calculated in the margins manager map.margin.Manager.

parameters.state

Type: Object

Object describing the state of a control.

options.useMapMargin true

Type: Boolean

Whether to use the map.margin.Manager map margins when showing search results on the map.

Examples:

1.

// Example 1.
// Creating a control and adding it to the map.
var searchControl = new ymaps.control.SearchControl({
     options: {
         float: 'right',
         floatIndex: 100,
         noPlacemark: true
     }
});
myMap.controls.add(searchControl);

2.

// Example 2.
// If the control was already added to the map using a key from the storage {@link control.storage},
// you can get its instance using the method {@link control.Manager.get}
// for the control manager {@link control.Manager}.

var searchControl = myMap.controls.get('searchControl');
searchControl.events.add('submit', function () {
    console.log('request: ' + searchControl.getRequestString());
}, this);

3.

// Example 3.
// Enabling business search in a control that's already been added to the map.
// If the control was already added to the map using а key from the storage {@link control.storage},
// you can get its instance using the method {@link control.Manager.get}

var searchControl = myMap.controls.get('searchControl');
searchControl.options.set('provider', 'yandex#search');

4.

// Example 4.
// Creating the "map search" control with business search enabled.

var searchControl = new ymaps.control.SearchControl({
     options: {
         float: 'left',
         provider: 'yandex#search'
     }
});

Fields

NameTypeDescription
events IEventManager

Event manager.

Inherited from IEventEmitter.

options IOptionManager

Options manager.

Inherited from IControl.

state data.Manager

State of the control. Names of fields that are available via the data.Manager.get method:

  • size - Current size of the control.
  • results - Array containing search results.
  • currentIndex - Index of the currently selected element.
  • found - Total number of results found.
  • request - Currently active query.
  • correction - Corrected query.
  • noSuggestPanel - Indicates whether the suggestion panel should be hidden.

Events

NameDescription
clear

Event of clearing the search results. Instance of the Event class.

error

Error in getting search results from the server event. Instance of the Event class. Names of fields that are available via the "Event.get" method:

  • error - Information about the error

load

Getting search results from the server event. Instance of the Event class. Names of fields that are available via the "Event.get" method:

  • skip - How many elements were omitted.
  • count - The number of downloaded items.

optionschange

Change to the object options.

Inherited from ICustomizable.

parentchange

The parent object reference changed.

Data fields:

  • oldParent - Old parent.
  • newParent - New parent.

Inherited from IChild.

resultselect

"Search result selection" event. Instance of the Event class. Names of fields that are available via the "Event.get" method:

  • index - Index of the selected result.

resultshow

Event for displaying search results. Instance of the Event class. Names of fields that are available via the "Event.get" method:

  • index - Index of the selected result.

submit

The event of sending a search query to the server. Instance of the Event class.

Methods

NameReturnsDescription
clear()

Clears the search results and the contents of the search bar control.

getMap() Map

Returns a reference to the map.

getParent()IControlParent | null

Returns a link to the parent object, or null if the parent element was not set.

Inherited from IControl.

getRequestString()String

Returns a search query.

getResponseMetaData()Object

Returns the geo search metadata.

getResult(index) vow.Promise

Getting search results.

getResultsArray()Object[]

Returns an array containing all current results.

getResultsCount()Integer

Returns the number of results found.

getSelectedIndex()Integer

Returns the index of the selected item.

hideResult()

Hides the result shown on the map.

search(request) vow.Promise

Performs the search.

setParent(parent) IChildOnMap

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.

showResult(index) control.SearchControl

Displays the result with the specified index.

Fields details

state

State of the control. Names of fields that are available via the data.Manager.get method:

  • size - Current size of the control.
  • results - Array containing search results.
  • currentIndex - Index of the currently selected element.
  • found - Total number of results found.
  • request - Currently active query.
  • correction - Corrected query.
  • noSuggestPanel - Indicates whether the suggestion panel should be hidden.

Events details

clear

clear

Event of clearing the search results. Instance of the Event class.

error

error

Error in getting search results from the server event. Instance of the Event class. Names of fields that are available via the "Event.get" method:

  • error - Information about the error

load

load

Getting search results from the server event. Instance of the Event class. Names of fields that are available via the "Event.get" method:

  • skip - How many elements were omitted.
  • count - The number of downloaded items.

resultselect

resultselect

"Search result selection" event. Instance of the Event class. Names of fields that are available via the "Event.get" method:

  • index - Index of the selected result.

resultshow

resultshow

Event for displaying search results. Instance of the Event class. Names of fields that are available via the "Event.get" method:

  • index - Index of the selected result.

submit

submit

The event of sending a search query to the server. Instance of the Event class.

Methods details

clear

clear()

Clears the search results and the contents of the search bar control.

getMap

{Map} getMap()

Returns a reference to the map.

getRequestString

{String} getRequestString()

Returns a search query.

getResponseMetaData

{Object} getResponseMetaData()

Returns the geo search metadata.

getResult

{vow.Promise} getResult(index)

Getting search results.

Returns an object of the vow.Promise type.

Parameters:

ParameterDefault valueDescription
index *
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Integer

Index of the result, starting from 0.

* Mandatory parameter/option.

getResultsArray

{Object[]} getResultsArray()

Returns an array containing all current results.

getResultsCount

{Integer} getResultsCount()

Returns the number of results found.

getSelectedIndex

{Integer} getSelectedIndex()

Returns the index of the selected item.

hideResult

hideResult()

Hides the result shown on the map.

Example:

// If we've displayed some result on the map using {@link control.SearchControl.showResult},
// or it's been displayed automatically during the search, we can hide it,
// e.g. by clicking a button.
var myButton = new ymaps.control.Button("Hide results");
myButton.events.add('click', function () {
    searchControl.hideResult();
}, this);
myMap.controls.add(myButton, { selectOnClick: false });

search

Performs the search.

Returns an object of the vow.Promise type.

Parameters:

ParameterDefault valueDescription
request *
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: String

Request.

* Mandatory parameter/option.

Example:

// Finding Moscow and outputting the "name" field
// from the first result to the console.
searchControl.search('Moscow').then(function () {
    var geoObjectsArray = searchControl.getResultsArray();
    if (geoObjectsArray.length) {
        // Outputs the "name" property of the first geo object in the search results.
        console.log(geoObjectsArray[0].properties.get('name'));
    }
});

showResult

Displays the result with the specified index.

Returns a self-reference.

Parameters:

ParameterDefault valueDescription
index *
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Integer

Index of the result, starting from 0.

* Mandatory parameter/option.

Example:

// We want to always show the first result,
// regardless of the number of objects
// found on the map (1 or more).
var searchControl = new ymaps.control.SearchControl({
    // This option disables automatically selecting search results.
    options: { noSelect: true }
});
searchControl.events.add('load', function (event) {
    // Verifying that this event is not completing results loading,
    // but that at least one result was found for the query.
    if (!event.get('skip') && searchControl.getResultsCount()) {
        searchControl.showResult(0);
    }
});