Geocoding Control API reference

This reference documents every object and method available. Each section describes classes or objects as well as their properties, parameters, methods, and associated events. Many sections also include inline code examples and related resources.

The GeocodingControl create a graphical component in your map application.

Example (create control with some not default options)



Options to provide to the GeocodingControl constructor (ControlOptions).


options.apiKey Maptiler API key. Not needed if used with MapTiler SDK.
A MapLibre GL JS instance to use when creating Markers. Used if options.marker is true with MapLibre GL JS library. If not provided it will be autodetected. Not needed if used with MapTiler SDK.
default: 200
Sets the amount of time, in milliseconds, to wait before querying the server when a user types into the Geocoder input box. This parameter may be useful for reducing the total number of API calls made for a single query.
default: [{ type: "server-geolocation" }]
Search results closer to the proximity point will be given higher priority. First matching rule from the array will be used. Set to `undefined` or `null` to disable proximity.
default: "Search"
Override the default placeholder attribute value.
default: "Something went wrong…"
Override the default error message.
default: "Oops! Looks like you're trying to predict something that's not quite right. We can't seem to find what you're looking for. Maybe try double-checking your spelling or try a different search term. Keep on typing - we'll do our best to get you where you need to go!"
Override the default message if no results are found.
default: true
If true, the geocoder proximity will automatically update based on the map view.
default: 2
Minimum number of characters to enter for results to show.
options.bbox A bounding box argument: this is a bounding box given as an array in the format [minX, minY, maxX, maxY]. Search results will be limited to the bounding box.
options.language Specify the language(s) to use for response text and query result weighting. Options are IETF language tags comprised of a mandatory ISO 639-1 language code and optionally one or more IETF subtags for country or script. More than one value can also be specified, separated by commas. Set to empty string or empty array for forcing no language preference. If this parameter is not provided at all the browser's language settings will be used.
default: true
If false, indicates that search will only occur on enter key press. If true, indicates that the Geocoder will search on the input box being updated above the minLength option.
(boolean | MarkerOptions)?
default: true
If true, a Marker will be added to the map at the location of the user-selected result using a default set of Marker options. If the value is an object, the marker will be constructed using these options. If false, no marker will be added to the map. Requires that options.maplibregl also be set.
(boolean | MarkerOptions)?
default: true
If true, a Marker will be added to the map at the location the top results for the query. If the value is an object, the marker will be constructed using these options. If false, no marker will be added to the map. Requires that options.maplibregl also be set.
default: 16
On geocoded result what zoom level should the map animate to when a bbox isn't found in the response. If a bbox is found the map will fit to the bbox.
(boolean | (FlyToOptions & FitBoundsOptions))?
default: true
If false, animating the map to a selected result is disabled. If true, animating the map will use the default animation parameters. If an object, it will be passed as options to the map flyTo or fitBounds method providing control over the animation of the transition.
default: false
If true, the geocoder control will collapse until hovered or in focus.
default: false
If true, the geocoder control will clear its value when the input blurs.
(feature: Feature) => boolean?
A function which accepts a Feature in the Carmen GeoJSON format to filter out results from the Geocoding API response before they are included in the suggestions list. Return true to keep the item, false otherwise.
options.class Class of the root element.
(boolean | "always")?
default: false
Set to true to enable reverse geocoding button with title. Set to "always" to reverse geocoding be always active.
default: "toggle reverse geocoding"
Reverse toggle button title.
Set to true to programatically toggle reverse mode. Useful only if enableReverse is true.
default: "clear"
Clear button title.
default: true
Set to true to show full feature geometry of the chosen result. Otherwise only marker will be shown.
options.fullGeometryStyle Style of the full feature geometry.
default: true
Set to false to disable fuzzy search.
default: 5
Maximum number of results to show.
default: undefined (use all countries)
Limit search to specified country(ies). Specify asalpha-2 ISO 3166 lowercase code.
default: undefined (all available feature types except poi are returned)
Filter of feature types to return. Check out the feature types list. For the poi feature type, it is possible also to add the PoiCategory as part of the query string. For example: coffee Java Hut.
default: false
Set to true to use all available feature types except those mentioned in types.
default: MapTiler Geocoding API URL
Geocoding API URL.
default: undefined
Extra fetch parameters.
default: "icons/" for Svelte apps, otherwise${version}/icons/
Base URL for POI icons.
(sp: URLSearchParams) => void
default: empty function
Function to adjust URL search parameters. The function receives a URLSearchParams as a parameter.
default: true
Automatically select the first feature from the result list.
default: false
Fly to selected feature from the result list.
default: true
Show marker on the selected feature from the result list.


Geocoding control available methods.


These events are implemented using EventTarget and CustomEvent.

To add a calback function to a event, do the following (Example of the optionsVisibilityChange event):