Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ubilabs/react-geosuggest

A React autosuggest for the Google Maps Places API.
https://github.com/ubilabs/react-geosuggest

Last synced: about 2 months ago
JSON representation

A React autosuggest for the Google Maps Places API.

Awesome Lists containing this project

README 

        
# React Geosuggest



A [React](https://reactjs.org/) autosuggest for the Google Maps Places API. You can also define your own suggests as defaults. Works with [Preact](https://github.com/developit/preact), too.



## Demo



Live demo: [ubilabs.github.io/react-geosuggest](https://ubilabs.github.io/react-geosuggest/)



## Installation



As this component uses the Google Maps Places API to get suggests, you must include the Google Maps Places API in the `` of your HTML:



```html



  

    …

    

  

  

    …

  



```



Visit the [Google Developer Console](https://console.developers.google.com) to generate your API key. The API's that you have to enable in your Google API Manager Dashboard are [Google Maps Geocoding API](https://developers.google.com/maps/documentation/geocoding/start), [Google Places API Web Service](https://developers.google.com/places/web-service/) and [Google Maps Javascript API](https://developers.google.com/maps/documentation/javascript/).



The easiest way to use geosuggest is to install it from NPM and include it in your own React build process (using [Webpack](https://webpack.github.io/), [Parcel](https://parceljs.org/), etc).



You can also use the standalone build by including `dist/react-geosuggest.js` in your page. If you use this, make sure you have already included React, and it is available as a global variable.



```sh

npm install @ubilabs/react-geosuggest --save

```



## Usage



The Geosuggest works out of the box by just including it. However, you can customize the behaviour with the properties noted below.



### ES6:



```js

import Geosuggest from '@ubilabs/react-geosuggest';



;

```



### ES5:



```js

var Geosuggest = require('@ubilabs/react-geosuggest').default;



;

```



### Properties



#### placeholder



Type: `String`

Default: `Search places`



The input field will get this placeholder text.



#### initialValue



Type: `String`

Default: `''`



An initial value for the input, when you want to prefill the suggest.



#### id



Type: `String`

Default: `''`



Define an ID for the geosuggest. Needed when there are multiple instances on a page.



#### className



Type: `String`

Default: `''`



Add an additional class to the geosuggest container.



#### style



Type: `Object`

Default: `{

  'input': {},

  'suggests': {},

  'suggestItem': {}

}`



Add an additional style to `Geosuggest`.

This would support overriding/adding styles to the input suggestList and suggestItem.



#### inputClassName



Type: `String`

Default: `''`



Add an additional class to the input.



#### disabled



Type: `Boolean`

Default: `false`



Defines whether the input is disabled.



#### location



Type: [`google.maps.LatLng`](https://developers.google.com/maps/documentation/javascript/reference#LatLng)

Default: `null`



To get localized suggestions, define a location to bias the suggests.



#### radius



Type: `Number`

Default: `0`



The radius in meters defines the area around the location to use for biasing the suggests. It must be accompanied by a `location` parameter.



#### bounds



Type: [`LatLngBounds`](https://developers.google.com/maps/documentation/javascript/reference?csw=1#LatLngBounds)

Default: `null`



The bounds to use for biasing the suggests. If this is set, `location` and `radius` are ignored.



#### country



Type: `String` or `Array`

Default: `null`



Restricts predictions to the specified country (ISO 3166-1 Alpha-2 country code, case insensitive). E.g., us, br, au. You can provide a single one, or an array of up to 5 country code strings.



#### types



Type: `Array`

Default: `null`



The types of predictions to be returned. Four types are supported: `establishment` for businesses, `geocode` for addresses, `(regions)` for administrative regions and `(cities)` for localities. If nothing is specified, all types are returned. Consult the Google Docs for [up to date types](https://developers.google.com/maps/documentation/javascript/reference/places-autocomplete-service#AutocompletionRequest.types).



#### fixtures



Type: `Array`

Default: `[]`



An array with fixtures (defaults). Each fixture has to be an object with a `label` key in it. Optionally provide a `location`, but the Geosuggest will geocode the label if no location is provided.



You can also add a `className` key to a fixture. This class will be applied to the fixture item.



#### maxFixtures



Type: `Number`

Default: `10`



Maximum number of fixtures to render.



#### placeDetailFields



Type: `Array`

Default: `null`



By default Google returns all fields when getting place details which can [impact billing](https://developers.google.com/maps/billing/understanding-cost-of-use#data-skus). You can optionally pass an [array of fields to include in place results](https://developers.google.com/maps/documentation/javascript/reference/places-service#PlaceDetailsRequest.fields) to limit what is returned and potentially reduce billing impact. `geometry` will always be added as we depend on the location for the suggest selection.



#### googleMaps



Type: `Object`

Default: `google.maps`



In case you want to provide your own Google Maps object, pass it in as googleMaps. The default is the global google maps object.



#### ignoreTab



Type: `Boolean`

Default: `false`



When the tab key is pressed, the `onSelect` handler is invoked. Set to true to not invoke `onSelect` on tab press.



#### ignoreEnter



Type: `Boolean`

Default: `false`



When the enter key is pressed, the `onSelect` handler is invoked. Set to true to not invoke `onSelect` on enter press.



#### queryDelay



Type: `Number`

Default: `250`



Sets the delay in milliseconds after typing before a request will be sent to find suggestions.

Specify `0` if you wish to fetch suggestions after every keystroke.



#### minLength



Type: `Number`

Default: `1`



Sets a minimum length of characters before a request will be sent to find suggestions.



#### highlightMatch



Type: `Boolean`

Default: `true`



Highlights matched text.



#### onFocus



Type: `Function`

Default: `function() {}`



Gets triggered when the input field receives focus.



#### onBlur



Type: `Function`

Default: `function(value) {}`



Gets triggered when input field loses focus.



#### onChange



Type: `Function`

Default: `function(value) {}`



Gets triggered when input field changes the value.



#### onKeyDown



Type: `Function`

Default: `function(event) {}`



Gets triggered when input field has a key pressed down. This event is triggered before onKeyPress.



#### onKeyPress



Type: `Function`

Default: `function(event) {}`



Gets triggered when input field gets key press.



#### onSuggestSelect



Type: `Function`

Default: `function(suggest) {}`



Gets triggered when a suggest got selected. Only parameter is an object with data of the selected suggest. This data is available:



- `label` – Type `String` – The label name

- `placeId` – Type `String` – If it is a preset, equals the `label`. Else it is the Google Maps `placeID`

- `location` – Type `Object` – The location containing `lat` and `lng`

- `gmaps` – Type `Object` – *Optional!* The complete response when there was a Google Maps geocode necessary (e.g. no location provided for presets). [Check the Google Maps Reference](https://developers.google.com/maps/documentation/javascript/reference#GeocoderResult) for more information on it’s structure.



#### onUpdateSuggests



Type: `Function`

Default: `function(suggests, activeSuggest) {}`



Gets triggered when the suggest list changes. Arguments include the suggest list and the current activeSuggest. Useful if you want to render the list of suggests outside of @ubilabs/react-geosuggest.



#### onActivateSuggest



Type: `Function`

Default: `function(suggest) {}`



Gets triggered when a suggest is activated in the list. Only parameter is an object with data of the selected suggest. This data is available:



- `label` – Type `String` – The label name

- `placeId` – Type `String` – If it is a preset, equals the `label`. Else it is the Google Maps `placeID`



#### onSuggestNoResults



Type: `Function`

Default: `function(userInput) {}`



Gets triggered when there are no suggest results found



#### getSuggestLabel



Type: `Function`

Default: `function(suggest) { return suggest.description; }`



Used to generate a custom label for a suggest. Only parameter is a suggest (google.maps.places.AutocompletePrediction). [Check the Google Maps Reference](https://developers.google.com/maps/documentation/javascript/reference#GeocoderResult) for more information on it’s structure.



#### renderSuggestItem



Type: `Function`

Default: `null`



Used to customize the inner html of SuggestItem and allows for controlling what properties of the suggest object you want to render. Also a convenient way to add additional styling to different rendered elements within SuggestItem. The function is passed both the suggestion and the user input.



#### skipSuggest



Type: `Function`

Default: `function(suggest) {}`



If the function returns true then the suggest will not be included in the displayed results. Only parameter is an object with data of the selected suggest. (See above)



#### autoActivateFirstSuggest



Type: `Boolean`

Default: `false`



Automatically activate the first suggestion as you type. If false, the exact term(s) in the input will be used when searching and may return a result not in the list of suggestions.



#### label



Type: `String`

Default: `null`



If the `label` and a `id` prop (see "Others") were supplied, a `` tag with the passed label text will be rendered. The `` element's `for` attribute will correctly point to the `id` of the `` element.



#### suggestsClassName



Type: `String`

Default: `''`



Add an additional class to suggest list.



#### suggestsHiddenClassName



Type: `String`

Default: `null`



Additional `className` to toggle as the list of suggestions changes visibility.



#### suggestItemClassName



Type: `String`

Default: `''`



Add an additional class to suggest item.



#### suggestItemActiveClassName



Type: `String`,

Default: `null`



Additional `className` to add when a suggestion item is active.



#### autoComplete



Type: `String`,

Default: `off`



Autocomplete input attribute.



#### inputType



Type: `String`,

Default: `text`



The value for the `type` attribute on the html input element. Can be either `text` or `search`.



#### Others



All [allowed attributes for `input[type="text"]`](https://github.com/ubilabs/react-geosuggest/blob/master/src/filter-input-attributes.ts#L4)

All [DOM clipboard events](https://facebook.github.io/react/docs/events.html#clipboard-events).

All [DOM mouse events](https://facebook.github.io/react/docs/events.html#mouse-events) except for drag & drop.

All [data attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/data-*).



### Exposed component functions



These functions are accessible by setting "ref" on the component (see example below)



#### focus()



Call `focus` to focus on the element. The suggest list will be expanded with the current suggestions.



#### blur()



Call `blur` to blur (unfocus) the element. The suggest list will be closed.



#### update(value)



It is possible to update the value of the input contained within the GeoSuggest component by calling the `update` function with a new desired `value` of the type String.



#### clear()



It is also possible to clear the value of the input contained within the GeoSuggest component by calling the `clear` function.



#### selectSuggest()



Same effect as hitting `enter` (will geocode the text inside of the input).



### Example



```jsx

import React, {useRef} from 'react';

import ReactDOM from 'react-dom/client';

import Geosuggest from '@ubilabs/react-geosuggest';



const App = () => {

  const geosuggestEl = useRef(null);



  const fixtures = [

    {label: 'New York', location: {lat: 40.7033127, lng: -73.979681}},

    {label: 'Rio', location: {lat: -22.066452, lng: -42.9232368}},

    {label: 'Tokyo', location: {lat: 35.673343, lng: 139.710388}}

  ];



  /**

   * When a suggest got selected

   */

  const onSuggestSelect = (suggest) => console.log(suggest);



  return (

    


      



      {* Buttons to trigger exposed component functions *}

      geosuggestEl.current.focus()}>Focus

      geosuggestEl.current.update('New Zealand')}>Update

      geosuggestEl.current.clear()}>Clear

      geosuggestEl.current.selectSuggest()}>Search

    


  );

};



const container = document.getElementById('app');

const root = ReactDOM.createRoot(container!);

root.render();

```



## Styling



This component uses [BEM](https://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/) for namespacing the CSS classes. So styling should be easy and without conflicts. See the [geosuggest.css](https://github.com/ubilabs/react-geosuggest/blob/master/src/geosuggest.css) for an example styling.



### Note:



The `geosuggest__suggests--hidden` class is added to hide the suggestion list. You should copy the style below into your CSS file.



```css

.geosuggest__suggests--hidden {

  max-height: 0;

  overflow: hidden;

  border-width: 0;

}

```



The above class is added whenever the suggestion list needs to be hidden. This occurs when the user selects an item from the list or when the user triggers the `blur` event on the input.



Similarly, you need to have the class `geosuggest__item--active` similar to this:



```css

.geosuggest__item--active {

  background: #267dc0;

  color: #fff;

}

```



to see what item is selected, f.ex. when using the arrow keys to navigate the suggestion list.



## Contributing



Issues and pull requests are welcome!

Please read the guidelines in [CONTRIBUTING.md](CONTRIBUTING.md) before starting to work on a PR.



## License



See [LICENSE.md](LICENSE.md)