control.SearchControl
Warning
To use a suggest in JS API:
- Get the key for the suggest in the developer's dashboard.
- 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 |
— |
Type: Object Control parameters. |
|
— |
Type: Object Object describing the data of a control. |
|
— |
Type: Object Control options. |
|
false |
Type: Boolean Whether the control registers its size in the map margins manager map.margin.Manager. |
|
— |
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. |
|
false |
Type: Boolean Whether to stretch control by the maximum width. |
|
"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. |
|
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". |
|
'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:
|
|
'house' |
Type: String Type of toponym (only for reverse geocoding). List of acceptable values:
|
|
'islands#searchControlLayout' |
Type: ISearchControlLayout|String Control layout. The layout constructor is passed an object containing the fields:
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. |
|
[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']. |
|
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. |
|
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. |
|
false |
Type: Boolean If true, the drop-down list of results is not shown; if false, it is shown. |
|
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. |
|
false |
Type: Boolean If true, the panel with the search suggestions is not shown; if false, it is shown. |
|
— |
Type: String Text of the hint, displayed in the input field of the control. |
|
'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:
|
|
'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:
|
|
— |
Type: Object Object describing the position of a control. If the position option is set, the float option value is automatically treated as "none". |
|
'auto' |
Type: Number|String Position relative to the bottom edge of the map. |
|
'auto' |
Type: Number|String Position relative to the left edge of the map. |
|
'auto' |
Type: Number|String Position relative to the right edge of the map. |
|
'auto' |
Type: Number|String Position relative to the top edge of the map. |
|
'yandex#map' |
Type: IGeocodeProvider|String Geocoding provider. One of the standard providers can be used:
|
|
'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. |
|
'auto' |
Type: String Defines the appearance of the control. Takes the following values:
|
|
— |
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. |
|
— |
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. |
|
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. |
|
— |
Type: Object Object describing the state of a control. |
|
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 |
Event manager. Inherited from IEventEmitter. |
||
Options manager. Inherited from IControl. |
||
State of the control. Names of fields that are available via the data.Manager.get method:
|
Events
Name |
Description |
Event of clearing the search results. Instance of the Event class. |
|
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:
|
|
Getting search results from the server event. Instance of the Event class. Names of fields that are available via the Event.get method:
|
|
Change to the object options. Inherited from ICustomizable. |
|
The parent object reference changed. Data fields:
Inherited from IChild. |
|
"Search result selection" event. Instance of the Event class. Names of fields that are available via the Event.get method:
|
|
Event for displaying search results. Instance of the Event class. Names of fields that are available via the Event.get method:
|
|
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() |
Returns reference to the map. |
|
IControlParent|null |
Returns link to the parent object, or null if the parent element was not set. Inherited from IControl. |
|
String |
Returns search query. |
|
Object |
Returns the geo search metadata. |
|
Getting search results. |
||
Object[] |
Returns array containing current search results. |
|
Integer |
Returns total number of results found. |
|
Integer |
Returns index of the selected element. |
|
Hides the result shown on the map. |
||
Performs the search. |
||
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. |
||
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 |
— |
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 });
search
{vow.Promise} search(request, options)
Performs the search.
Returns object of type vow.Promise.
Parameters:
Parameter |
Default value |
Description |
— |
Type: String Request. |
|
— |
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 |
— |
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);
}
});
Mandatory parameter/option.