places-autocomplete

This library provides an autocomplete component for the Mapbox Geocoding API.

Getting Started

Install the package:

npm install --save places-autocomplete

Import and initialize the autocomplete:

import mapboxgl from 'mapbox-gl';
import PlacesAutocomplete from 'places-autocomplete';
import 'places-autocomplete/index.css';

mapboxgl.accessToken = 'pk.abcd1234...';

const mapboxglMap = new mapboxgl.Map({
  container: document.getElementById('my-map-container'),
  style: 'mapbox://styles/mapbox/streets-v12'
});

const autocomplete = new PlacesAutocomplete({
  mapboxToken: mapboxgl.accessToken,
  mapInstance: mapboxglMap,
  debounce: 300
});

const inputEl = document.getElementById('my-input');
autocomplete.attachTo(inputEl);

The example above configures the autocomplete with a mapbox-gl map instance, allowing the autocomplete to sync the map's position to the selected autocomplete result. You can view the Mapbox GL JS docs for more information on the mapbox-gl package.

Options

The autocomplete can be configured with the following options upon initialization:

| Option | Description | Default | | -------------------------- | -------------------------------------------------------------------------- | ---------------- | | input | An input DOM element to attach the autocomplete to. | - | | mapboxToken | The Mapbox access token used for the API requests (required). | - | | mapInstance | A mapboxgl.Map instance, syncs map position to autocomplete. | - | | className | Specifies the class name for the autocomplete suggestions container. | - | | minLength | Minimum number of characters needed to trigger autocomplete. | 2 | | debounce | Time in milliseconds to delay the autocomplete between keystrokes. | 200 | | preventSubmit | If true, prevents the input from submitting its form on Enter. | false | | limit | Number of results to return in the autocomplete. | 6 | | language | Language of returned Mapbox autocomplete results. | browser language | | proximity | Favor results that are closer to this location. Given as a string of two comma-separated coordinates ("lon,lat"). If a mapInstance is specified then the map's current center position will be used instead. | - | | featureTypes | Filter results to include only a subset of the available feature types. Multiple types can be comma-separated. Options are: country, region, postcode, district, place, locality, neighborhood, address, and poi. | - | | additionalResultsPrepend | If true, prepends additionalResults entries to autocomplete suggestions. | false | | onClear | Function called when input is cleared. | - | | onSelect | Function called when autocomplete item is selected (args: [item]). | - | | additionalResults | Function called before updating autocomplete results, should return array of results (args: [query]). | - | | customize | Function called before rendering autocomplete results (args: [input, inputRect, container, maxHeight]). | - |

License

The library is available as open source under the terms of the MIT License.