diff --git a/docs/img/src/mapbox-gl-geocoder-custom-render.png b/docs/img/src/mapbox-gl-geocoder-custom-render.png
new file mode 100644
index 00000000000..639e38f4f2e
Binary files /dev/null and b/docs/img/src/mapbox-gl-geocoder-custom-render.png differ
diff --git a/docs/img/src/mapbox-gl-geocoder-proximity-bias.png b/docs/img/src/mapbox-gl-geocoder-proximity-bias.png
deleted file mode 100644
index 76cc476515c..00000000000
Binary files a/docs/img/src/mapbox-gl-geocoder-proximity-bias.png and /dev/null differ
diff --git a/docs/img/src/mapbox-gl-geocoder-with-flyto.png b/docs/img/src/mapbox-gl-geocoder-with-flyto.png
new file mode 100644
index 00000000000..639e38f4f2e
Binary files /dev/null and b/docs/img/src/mapbox-gl-geocoder-with-flyto.png differ
diff --git a/docs/img/src/mapbox-gl-geocoder-with-language.png b/docs/img/src/mapbox-gl-geocoder-with-language.png
new file mode 100644
index 00000000000..639e38f4f2e
Binary files /dev/null and b/docs/img/src/mapbox-gl-geocoder-with-language.png differ
diff --git a/docs/pages/example/forward-geocode-custom-data.html b/docs/pages/example/forward-geocode-custom-data.html
index f8fe3896e46..30d83a5bb53 100644
--- a/docs/pages/example/forward-geocode-custom-data.html
+++ b/docs/pages/example/forward-geocode-custom-data.html
@@ -1,5 +1,5 @@
-<script src='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v3.1.6/mapbox-gl-geocoder.min.js'></script>
-<link rel='stylesheet' href='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v3.1.6/mapbox-gl-geocoder.css' type='text/css' />
+<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' />
 <div id='map'></div>
 
 <script>
@@ -163,6 +163,7 @@
     accessToken: mapboxgl.accessToken,
     localGeocoder: forwardGeocoder,
     zoom: 14,
-    placeholder: "Enter search e.g. Lincoln Park"
+    placeholder: "Enter search e.g. Lincoln Park",
+    mapboxgl: mapboxgl
 }));
 </script>
diff --git a/docs/pages/example/mapbox-gl-geocoder-accept-coordinates.html b/docs/pages/example/mapbox-gl-geocoder-accept-coordinates.html
index 9ff58dbfc3d..0f130f09a7f 100644
--- a/docs/pages/example/mapbox-gl-geocoder-accept-coordinates.html
+++ b/docs/pages/example/mapbox-gl-geocoder-accept-coordinates.html
@@ -1,5 +1,5 @@
-<script src='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v3.1.6/mapbox-gl-geocoder.min.js'></script>
-<link rel='stylesheet' href='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v3.1.6/mapbox-gl-geocoder.css' type='text/css' />
+<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' />
 <div id='map'></div>
 
 <script>
@@ -28,7 +28,7 @@
                 type: "Point",
                 coordinates: [lng, lat]
             },
-            place_name: 'Lat: ' + lat + ', Lng: ' + lng, // eslint-disable-line camelcase
+            place_name: 'Lat: ' + lat + ' Lng: ' + lng, // eslint-disable-line camelcase
             place_type: ['coordinate'], // eslint-disable-line camelcase
             properties: {},
             type: 'Feature'
@@ -62,6 +62,7 @@
     accessToken: mapboxgl.accessToken,
     localGeocoder: coordinatesGeocoder,
     zoom: 4,
-    placeholder: "Try: -40, 170"
+    placeholder: "Try: -40, 170",
+    mapboxgl: mapboxgl
 }));
 </script>
diff --git a/docs/pages/example/mapbox-gl-geocoder-custom-render.html b/docs/pages/example/mapbox-gl-geocoder-custom-render.html
new file mode 100644
index 00000000000..b4e06f18695
--- /dev/null
+++ b/docs/pages/example/mapbox-gl-geocoder-custom-render.html
@@ -0,0 +1,39 @@
+<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' />
+<style>
+.geocoder-dropdown-item{
+    padding: 5px
+}
+.geocoder-dropdown-icon{
+    margin-right: 10px;
+}
+.geocoder-dropdown-text{
+    color: #5a3fc0;
+    font-family: Arial, Helvetica, sans-serif;
+    font-size: larger;
+}
+</style>
+<div id='map'></div>
+
+<script>
+var map = new mapboxgl.Map({
+    container: 'map',
+    style: 'mapbox://styles/mapbox/streets-v9',
+    center: [-79.4512, 43.6568],
+    zoom: 13
+});
+
+var geocoder = new MapboxGeocoder({
+    accessToken: mapboxgl.accessToken,
+    types: 'poi',
+    // see https://docs.mapbox.com/api/search/#geocoding-response-object for information about the schema of each response feature
+    render: function(item) {
+        // extract the item's maki icon or use a default
+        var maki = item.properties.maki || 'marker';
+        return "<div class='geocoder-dropdown-item'><img class='geocoder-dropdown-icon' src='https://unpkg.com/@mapbox/maki@6.1.0/icons/" + maki + "-15.svg'><span class='geocoder-dropdown-text'>" + item.text + "</span></div>";
+    },
+    mapboxgl: mapboxgl
+});
+map.addControl(geocoder);
+
+</script>
diff --git a/docs/pages/example/mapbox-gl-geocoder-custom-render.js b/docs/pages/example/mapbox-gl-geocoder-custom-render.js
new file mode 100644
index 00000000000..f24fdffbab5
--- /dev/null
+++ b/docs/pages/example/mapbox-gl-geocoder-custom-render.js
@@ -0,0 +1,12 @@
+/*---
+title: Use a custom render function with a geocoder
+description: >-
+  Use a custom html rendering function with the [mapbox-gl-geocoder](https://github.com/mapbox/mapbox-gl-geocoder)
+  to customize how the dropdown menu is displayed.
+tags:
+  - geocoder
+pathname: /mapbox-gl-js/example/mapbox-gl-geocoder-custom-render/
+---*/
+import Example from '../../components/example';
+import html from './mapbox-gl-geocoder-custom-render.html';
+export default Example(html);
diff --git a/docs/pages/example/mapbox-gl-geocoder-limit-region.html b/docs/pages/example/mapbox-gl-geocoder-limit-region.html
index 19bd879e75e..55893c31a22 100644
--- a/docs/pages/example/mapbox-gl-geocoder-limit-region.html
+++ b/docs/pages/example/mapbox-gl-geocoder-limit-region.html
@@ -1,5 +1,5 @@
-<script src='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v3.1.6/mapbox-gl-geocoder.min.js'></script>
-<link rel='stylesheet' href='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v3.1.6/mapbox-gl-geocoder.css' type='text/css' />
+<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' />
 <div id='map'></div>
 
 <script>
@@ -31,6 +31,7 @@
         }).reduce(function (acc, cur) {
             return acc || cur;
         });
-    }
+    },
+    mapboxgl: mapboxgl
 }));
 </script>
diff --git a/docs/pages/example/mapbox-gl-geocoder-outside-the-map.html b/docs/pages/example/mapbox-gl-geocoder-outside-the-map.html
index 419eb35f429..f9a1c06f8a7 100644
--- a/docs/pages/example/mapbox-gl-geocoder-outside-the-map.html
+++ b/docs/pages/example/mapbox-gl-geocoder-outside-the-map.html
@@ -1,5 +1,5 @@
-<script src='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v3.1.6/mapbox-gl-geocoder.min.js'></script>
-<link rel='stylesheet' href='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v3.1.6/mapbox-gl-geocoder.css' type='text/css' />
+<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' />
 <style>
     .geocoder {
         position:absolute;
@@ -23,7 +23,8 @@
 });
 
 var geocoder = new MapboxGeocoder({
-    accessToken: mapboxgl.accessToken
+    accessToken: mapboxgl.accessToken,
+    mapboxgl: mapboxgl
 });
 
 document.getElementById('geocoder').appendChild(geocoder.onAdd(map));
diff --git a/docs/pages/example/mapbox-gl-geocoder-proximity-bias.html b/docs/pages/example/mapbox-gl-geocoder-proximity-bias.html
deleted file mode 100644
index bfec7c0a0bb..00000000000
--- a/docs/pages/example/mapbox-gl-geocoder-proximity-bias.html
+++ /dev/null
@@ -1,31 +0,0 @@
-<script src='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v3.1.6/mapbox-gl-geocoder.min.js'></script>
-<link rel='stylesheet' href='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v3.1.6/mapbox-gl-geocoder.css' type='text/css' />
-<div id='map'></div>
-
-<script>
-var map = new mapboxgl.Map({
-    container: 'map',
-    style: 'mapbox://styles/mapbox/streets-v11',
-    center: [-79.4512, 43.6568],
-    zoom: 13
-});
-
-var geocoder = new MapboxGeocoder({
-    accessToken: mapboxgl.accessToken
-});
-map.addControl(geocoder);
-
-map.on('load', updateGeocoderProximity); // set proximity on map load
-map.on('moveend', updateGeocoderProximity); // and then update proximity each time the map moves
-
-function updateGeocoderProximity() {
-    // proximity is designed for local scale, if the user is looking at the whole world,
-    // it doesn't make sense to factor in the arbitrary centre of the map
-    if (map.getZoom() > 9) {
-        var center = map.getCenter().wrap(); // ensures the longitude falls within -180 to 180 as the Geocoding API doesn't accept values outside this range
-        geocoder.setProximity({ longitude: center.lng, latitude: center.lat });
-    } else {
-        geocoder.setProximity(null);
-    }
-}
-</script>
diff --git a/docs/pages/example/mapbox-gl-geocoder-proximity-bias.js b/docs/pages/example/mapbox-gl-geocoder-proximity-bias.js
deleted file mode 100644
index 626c7fbccdb..00000000000
--- a/docs/pages/example/mapbox-gl-geocoder-proximity-bias.js
+++ /dev/null
@@ -1,13 +0,0 @@
-/*---
-title: Bias geocoder results around the map view
-description: >-
-  Use the [mapbox-gl-geocoder](https://github.com/mapbox/mapbox-gl-geocoder)
-  control to search for places using Mapbox Geocoding API biasing results
-  nearby the map's current view.
-tags:
-  - geocoder
-pathname: /mapbox-gl-js/example/mapbox-gl-geocoder-proximity-bias/
----*/
-import Example from '../../components/example';
-import html from './mapbox-gl-geocoder-proximity-bias.html';
-export default Example(html);
diff --git a/docs/pages/example/mapbox-gl-geocoder-with-flyto.html b/docs/pages/example/mapbox-gl-geocoder-with-flyto.html
new file mode 100644
index 00000000000..ea3117aa747
--- /dev/null
+++ b/docs/pages/example/mapbox-gl-geocoder-with-flyto.html
@@ -0,0 +1,30 @@
+<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' />
+<div id='map'></div>
+
+<script>
+var map = new mapboxgl.Map({
+    container: 'map',
+    style: 'mapbox://styles/mapbox/streets-v9',
+    center: [-79.4512, 43.6568],
+    zoom: 13
+});
+
+var geocoder = new MapboxGeocoder({
+    accessToken: mapboxgl.accessToken,
+    flyTo: {
+        bearing: 0,
+        // These options control the flight curve, making it move
+        // slowly and zoom out almost completely before starting
+        // to pan.
+        speed: 0.2, // make the flying slow
+        curve: 1, // change the speed at which it zooms out
+        // This can be any easing function: it takes a number between
+        // 0 and 1 and returns another number between 0 and 1.
+        easing: function (t) { return t; }
+    },
+    mapboxgl: mapboxgl
+});
+map.addControl(geocoder);
+
+</script>
diff --git a/docs/pages/example/mapbox-gl-geocoder-with-flyto.js b/docs/pages/example/mapbox-gl-geocoder-with-flyto.js
new file mode 100644
index 00000000000..3120b65e6e5
--- /dev/null
+++ b/docs/pages/example/mapbox-gl-geocoder-with-flyto.js
@@ -0,0 +1,12 @@
+/*---
+title: Use a custom camera animation with a geocoder
+description: >-
+  Use camera animation options with the [mapbox-gl-geocoder](https://github.com/mapbox/mapbox-gl-geocoder)
+  to create a custom animation when a result is selected.
+tags:
+  - geocoder
+pathname: /mapbox-gl-js/example/mapbox-gl-geocoder-with-flyto/
+---*/
+import Example from '../../components/example';
+import html from './mapbox-gl-geocoder-with-flyto.html';
+export default Example(html);
diff --git a/docs/pages/example/mapbox-gl-geocoder-with-language.html b/docs/pages/example/mapbox-gl-geocoder-with-language.html
new file mode 100644
index 00000000000..8efefca9237
--- /dev/null
+++ b/docs/pages/example/mapbox-gl-geocoder-with-language.html
@@ -0,0 +1,20 @@
+<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' />
+<div id='map'></div>
+
+<script>
+var map = new mapboxgl.Map({
+    container: 'map',
+    style: 'mapbox://styles/mapbox/streets-v9',
+    center: [-79.4512, 43.6568],
+    zoom: 13
+});
+
+var geocoder = new MapboxGeocoder({
+    accessToken: mapboxgl.accessToken,
+    language: 'de-DE',
+    mapboxgl: mapboxgl
+});
+map.addControl(geocoder);
+
+</script>
diff --git a/docs/pages/example/mapbox-gl-geocoder-with-language.js b/docs/pages/example/mapbox-gl-geocoder-with-language.js
new file mode 100644
index 00000000000..ec340fc2170
--- /dev/null
+++ b/docs/pages/example/mapbox-gl-geocoder-with-language.js
@@ -0,0 +1,12 @@
+/*---
+title: Localize the geocoder to a given language
+description: >-
+  Localize the [mapbox-gl-geocoder](https://github.com/mapbox/mapbox-gl-geocoder)
+  to set the UI language and improve result relevance in that language.
+tags:
+  - geocoder
+pathname: /mapbox-gl-js/example/mapbox-gl-geocoder-with-language/
+---*/
+import Example from '../../components/example';
+import html from './mapbox-gl-geocoder-with-language.html';
+export default Example(html);
diff --git a/docs/pages/example/mapbox-gl-geocoder.html b/docs/pages/example/mapbox-gl-geocoder.html
index 41213eed036..6ee1cc93499 100644
--- a/docs/pages/example/mapbox-gl-geocoder.html
+++ b/docs/pages/example/mapbox-gl-geocoder.html
@@ -1,5 +1,5 @@
-<script src='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v3.1.6/mapbox-gl-geocoder.min.js'></script>
-<link rel='stylesheet' href='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v3.1.6/mapbox-gl-geocoder.css' type='text/css' />
+<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' />
 <div id='map'></div>
 
 <script>
@@ -11,6 +11,7 @@
 });
 
 map.addControl(new MapboxGeocoder({
-    accessToken: mapboxgl.accessToken
+    accessToken: mapboxgl.accessToken,
+    mapboxgl: mapboxgl
 }));
 </script>
diff --git a/docs/pages/example/point-from-geocoder-result.html b/docs/pages/example/point-from-geocoder-result.html
index be777673ead..344cbb6c85b 100644
--- a/docs/pages/example/point-from-geocoder-result.html
+++ b/docs/pages/example/point-from-geocoder-result.html
@@ -1,5 +1,5 @@
-<script src='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v3.1.6/mapbox-gl-geocoder.min.js'></script>
-<link rel='stylesheet' href='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-geocoder/v3.1.6/mapbox-gl-geocoder.css' type='text/css' />
+<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' />
 <style>
 #geocoder-container > div {
     min-width:50%;
@@ -17,36 +17,13 @@
 });
 
 var geocoder = new MapboxGeocoder({
-    accessToken: mapboxgl.accessToken
+    accessToken: mapboxgl.accessToken,
+    marker: {
+        color: 'orange'
+    },
+    mapboxgl: mapboxgl
 });
 
 map.addControl(geocoder);
 
-// After the map style has loaded on the page, add a source layer and default
-// styling for a single point.
-map.on('load', function() {
-    map.addSource('single-point', {
-        "type": "geojson",
-        "data": {
-            "type": "FeatureCollection",
-            "features": []
-        }
-    });
-
-    map.addLayer({
-        "id": "point",
-        "source": "single-point",
-        "type": "circle",
-        "paint": {
-            "circle-radius": 10,
-            "circle-color": "#007cbf"
-        }
-    });
-
-    // Listen for the `result` event from the MapboxGeocoder that is triggered when a user
-    // makes a selection and add a symbol that matches the result.
-    geocoder.on('result', function(ev) {
-        map.getSource('single-point').setData(ev.result.geometry);
-    });
-});
 </script>
diff --git a/docs/pages/example/point-from-geocoder-result.js b/docs/pages/example/point-from-geocoder-result.js
index 4799287e3d5..015c45e3166 100644
--- a/docs/pages/example/point-from-geocoder-result.js
+++ b/docs/pages/example/point-from-geocoder-result.js
@@ -1,10 +1,8 @@
 /*---
 title: Set a point after Geocoder result
 description: >-
-  Listen to the
-  [`result`](https://github.com/mapbox/mapbox-gl-geocoder/blob/master/API.md#on)
-  event from [mapbox-gl-geocoder](https://github.com/mapbox/mapbox-gl-geocoder)
-  and place a point on the coordinate results.
+  Style a [Marker](https://docs.mapbox.com/mapbox-gl-js/api/#marker) used to mark the location of the [mapbox-gl-geocoder](https://github.com/mapbox/mapbox-gl-geocoder)
+  result.
 tags:
   - geocoder
 pathname: /mapbox-gl-js/example/point-from-geocoder-result/