control.SearchControl

Warning

To use a suggest in JS API:

  1. Get the key for the suggest in the developer's dashboard.
  2. Specify it when connecting the JS API in the format https://api-maps.yandex.ru/2.1/?lang=ru_RU&apikey=<your key for JS API>&suggest_apikey=<your key for Suggest API>.

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.

Key for the control in control.storage — "searchControl".

Constructor | Fields | Events | Methods

Constructor

control.SearchControl([parameters])

Parameters:

Parameter

Default value

Description

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 size 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.fitMaxWidth

false

Type: Boolean

Whether to stretch control by the maximum width.

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

Constructor of the form layout for searching in the default control layout or the key in storage 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, 315]

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 set in the instance of the class control.Manager, which is usually a field of Map.controls, via the "states" option. Default search control layout width for large state can be set in range from 280 to 660 pixels. 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

Layout constructor for a search result in the drop-down list in the default control layout or the key in storage 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

Layout constructor for the drop-down list with search results in the default control layout or the key in storage 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.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

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 "useMapMargin" option 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 account for map margins map.margin.Manager 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 control.storage,
// you can get its instance using the control.Manager.get method
// for control.Manager.

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

3.

// Example 3.
// Enabling the business search in a control that is already added to the map.
// If the control was already added to the map using a key from control.storage,
// you can get its instance using the control.Manager.get method.

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'
     }
});

5.

// Example 5.
// Enlarging search control in "large" state.
map.options.set({
    // Default option value is [30, 72, 315],
    // we need to correct only value for "large" state.
    searchControlMaxWidth: [30, 72, 500],
    // Expand large search control to maxWidth.
    fitMaxWidth: true
});

Fields

Name

Type

Description

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

Name

Description

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

Name

Returns

Description

clear()

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

getMap()

Map

Returns reference to the map.

getParent()

IControlParent|null

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

Inherited from IControl.

getRequestString()

String

Returns search query.

getResponseMetaData()

Object

Returns the geo search metadata.

getResult(index)

vow.Promise

Getting search results.

getResultsArray()

Object[]

Returns array containing current search results.

getResultsCount()

Integer

Returns total number of results found.

getSelectedIndex()

Integer

Returns index of the selected element.

hideResult()

Hides the result shown on the map.

search(request, options)

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

{data.Manager} 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

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.

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 details

clear

{} clear()

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

getMap

{Map} getMap()

Returns reference to the map.

getRequestString

{String} getRequestString()

Returns search query.

getResponseMetaData

{Object} getResponseMetaData()

Returns the geo search metadata.

getResult

{vow.Promise} getResult(index)

Getting search results.

Returns object of type vow.Promise.

Parameters:

Parameter

Default value

Description

index*

Type: Integer

Index of the result, starting from 0.

* Mandatory parameter/option.

getResultsArray

{Object[]} getResultsArray()

Returns array containing current search results.

getResultsCount

{Integer} getResultsCount()

Returns total number of results found.

getSelectedIndex

{Integer} getSelectedIndex()

Returns index of the selected element.

hideResult

{} hideResult()

Hides the result shown on the map.

Example:

// If we showed a result on the map using control.SearchControl.showResult,
// or it was displayed automatically during search, we can hide it, for example,
// when the button is clicked.
var myButton = new ymaps.control.Button("Hide results");
myButton.events.add('click', function () {
    searchControl.hideResult();
}, this);
myMap.controls.add(myButton, { selectOnClick: false });
{vow.Promise} search(request, options)

Performs the search.

Returns object of type vow.Promise.

Parameters:

Parameter

Default value

Description

request*

Type: String

Request.

options*

Type: Object

Additional provider options.

* 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

{control.SearchControl} showResult(index)

Displays the result with the specified index.

Returns self-reference.

Parameters:

Parameter

Default value

Description

index*

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);
    }
});