Mapbox-gl-geocoder version 4

More customizable, relevant search for web

By: Scott Farley

We just released a new version of the mapbox-gl-geocoder plugin to add search to your web or mobile app. The latest release, version 4, allows you to completely customize how results are rendered, automatically detect the user’s language, set search proximity by default, and more.

Custom styling

Add custom styling, icons, or text to the items in the dropdown using the plugin’s render function. The render function takes a GeoJSON feature in the search results and returns a string of HTML to render in the display. You can set the function when you create the plugin by setting options.render, or you can set it later using the setRenderFunction API.

For example: change the styling and add Maki icons to the dropdown menu to match the styling on your map or the rest of the content on the page. Create a custom render function that assigns a new CSS class to the dropdown elements and then sets the color property to match whatever color you want.

<style>
.geocoder-menu-item{
    color: #28C2FF;
}
</style>

<script>
...
function render(feature){
    return `<span class='geocoder-menu-item'>${feature.place_name}</span>`
}

geocoder.setRenderFunction(render);

</script>

Check out this example of using the render function to add Maki icons to the dropdown.

Better internationalization

The new version of gl-geocoder improves the experience for users around the world by offering customization of language settings. By default, the gl-geocoder will inspect the user’s browser preferences and localize the plugin to the user’s default language (including setting the placeholder text in the search bar). You can also override the default placeholder and language settings by setting a language parameter.

The render function can also be used to improve the results returned to users. For example, you can set a render function that sets the place_name_de fields for your German-speaking users while setting the place_name_fr for those in France.

See this example of localizing the plugin’s language and placeholder.

Localization by default

In addition to improved customizability and localization, gl-geocoder now has new default behavior that improves the relevance of results. Version 4 automatically sets the proximity point for the request to the center of the user’s current map view and the language to the plugin’s language or the browser’s default language.

The plugin will also default to adding a marker to the location of the selected feature so that users will be aware of the exact location of the feature they’ve selected.

Because the plugin calls the Mapbox Search API, you still have full control over all the API options for complete customization.

Add mapbox-gl-geocoder to your map!

First, include the package’s JavaScript and CSS files from our CDN (also available on npm).

<script src=’https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v4.0.0/mapbox-gl-geocoder.min.js'></script>

<link rel=’stylesheet’ href=’https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v4.0.0/mapbox-gl-geocoder.css' type=’text/css’ />

Next, create a new geocoder control. See the API docs for more options and fine-grained control over behavior.

var geocoder = new MapboxGeocoder({
   accessToken: mapboxgl.accessToken,
   mapboxgl: mapboxgl
});

Finally, add the geocoder to your map as a Control.

map.addControl(geocoder);

Here’s the full example of setting up the map and geocoder together.

We’d love to hear your thoughts. Pick up the conversation on Twitter or head on over to https://github.com/mapbox/mapbox-gl-geocoder and open a ticket or pull request.

Scott Farley

Mapbox-gl-geocoder version 4 was originally published in Points of interest on Medium, where people are continuing the conversation by highlighting and responding to this story.