Skip to content

Search

A search box floating over the map. It can search for places (with a geocoder), for features in your layers, or both.

  • id: search
  • Surfaces: floating
  • Notes: it has no title bar; the search bar is the whole pop-out, and clicking the icon again closes it. It also works with stayOnMobile, so it can stay over the map on phones instead of opening in the bottom sheet. The bar always opens sideways, toward the middle of the map, even in a horizontal corner; a placement can change that with "opens": "vertically".

Place it

"floatingWidgets": [
  {
    "slot": "top-left",
    "widgets": [{ "widgetName": "search", "order": -1, "stayOnMobile": true }]
  }
]

"order": -1 puts it above the zoom control in the same corner, and "stayOnMobile": true keeps the small bar over the map on phones.

Configuration: settings.search

"search": {
  "geocoder": { "provider": "nominatim", "limit": 3 },
  "layers": [
    { "layerId": "airports", "fields": ["name"], "labelField": "name", "limit": 3, "pointZoom": 12 },
    { "layerId": "power-plants", "fields": ["plant_name"], "labelField": "plant_name" }
  ],
  "placeholder": "Search places, airports, or power plants…",
  "pointZoom": 14,
  "sectionOrder": "features-first"
}

Top-level fields

Field Type Default Description
geocoder GeocoderConfig none Place search (below). Leave it out to search layers only
layers SearchableLayerConfig[] none Layers to search (below). Leave it out to search places only
placeholder string "Search…" Text in the empty search box
pointZoom number 14 Zoom when flying to a point result. Other results fit their bounds
sectionOrder "features-first" \| "places-first" "features-first" Whether layer results or "Places" come first
loadingText string "Searching…" Change it for other languages
noResultsText string "No results." Change it for other languages

Geocoder: search.geocoder

Field Type Default Description
provider "nominatim" \| "maptiler" required nominatim needs no key (OpenStreetMap; light use only, attribution required). maptiler needs an apiKey
apiKey string none Required for maptiler. Anyone using your app can see it, so restrict it to your domain; see API Keys & Security
endpoint string provider default A different request URL, e.g. a self-hosted Nominatim
limit number 5 Max place results

Searchable layers: search.layers[]

Only GeoJSON layers can be searched, because the search needs all of a layer's features. PMTiles and other tiled layers are skipped, with a console warning. If a layer is filtered, only features that pass the filter show up. A layer whose file fails to load (moved, missing, offline) is left out with a console warning; the other layers and the place results still show.

Field Type Default Description
layerId string required A layer id from settings.layers
fields string[] required Properties to search; matches any part of the value, ignoring case
labelField string first of fields Property shown as the result label
limit number 8 Max results for this layer
pointZoom number search.pointZoom Zoom for point results from this layer