{"id":13421993,"url":"https://github.com/ubilabs/react-geosuggest","last_synced_at":"2025-10-22T15:56:13.517Z","repository":{"id":27402998,"uuid":"30879530","full_name":"ubilabs/react-geosuggest","owner":"ubilabs","description":"A React autosuggest for the Google Maps Places API.","archived":false,"fork":false,"pushed_at":"2025-01-08T11:31:16.000Z","size":2979,"stargazers_count":1043,"open_issues_count":20,"forks_count":326,"subscribers_count":24,"default_branch":"main","last_synced_at":"2025-03-08T09:36:35.402Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://ubilabs.github.io/react-geosuggest/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ubilabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-02-16T17:31:00.000Z","updated_at":"2025-03-07T19:28:44.000Z","dependencies_parsed_at":"2023-10-11T20:59:39.524Z","dependency_job_id":"f3f4728e-6bca-480d-bf6d-458ef50d298a","html_url":"https://github.com/ubilabs/react-geosuggest","commit_stats":{"total_commits":429,"total_committers":94,"mean_commits":"4.5638297872340425","dds":0.6340326340326341,"last_synced_commit":"267b4ac4a200391d7cf295a1a5868d6b58fc9b85"},"previous_names":[],"tags_count":67,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ubilabs%2Freact-geosuggest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ubilabs%2Freact-geosuggest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ubilabs%2Freact-geosuggest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ubilabs%2Freact-geosuggest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ubilabs","download_url":"https://codeload.github.com/ubilabs/react-geosuggest/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243719094,"owners_count":20336591,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T23:00:35.122Z","updated_at":"2025-10-22T15:56:08.472Z","avatar_url":"https://github.com/ubilabs.png","language":"TypeScript","funding_links":[],"categories":["UI Components","Uncategorized","Demos","\u003csummary\u003eUI Components\u003c/summary\u003e","TypeScript"],"sub_categories":["Map","Uncategorized","Data Visualization"],"readme":"# React Geosuggest\n\nA [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.\n\n## Demo\n\nLive demo: [ubilabs.github.io/react-geosuggest](https://ubilabs.github.io/react-geosuggest/)\n\n## Installation\n\nAs this component uses the Google Maps Places API to get suggests, you must include the Google Maps Places API in the `\u003chead\u003e` of your HTML:\n\n```html\n\u003c!doctype html\u003e\n\u003chtml\u003e\n  \u003chead\u003e\n    …\n    \u003cscript src=\"https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY_HERE\u0026libraries=places\"\u003e\u003c/script\u003e\n  \u003c/head\u003e\n  \u003cbody\u003e\n    …\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\nYou can use [@ubilabs/react-google-maps](https://github.com/visgl/react-google-maps) to initialize the Google Maps API and load the require Google Maps libraries.\n\nVisit 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/).\n\nThe 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).\n\nYou 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.\n\n```sh\nnpm install @ubilabs/react-geosuggest --save\n```\n\n## Usage\n\nThe Geosuggest works out of the box by just including it. However, you can customize the behaviour with the properties noted below.\n\n### ES6:\n\n```js\nimport Geosuggest from '@ubilabs/react-geosuggest';\n\n\u003cGeosuggest /\u003e;\n```\n\n### ES5:\n\n```js\nvar Geosuggest = require('@ubilabs/react-geosuggest').default;\n\n\u003cGeosuggest /\u003e;\n```\n\n### Properties\n\n#### placeholder\n\nType: `String`\nDefault: `Search places`\n\nThe input field will get this placeholder text.\n\n#### initialValue\n\nType: `String`\nDefault: `''`\n\nAn initial value for the input, when you want to prefill the suggest.\n\n#### id\n\nType: `String`\nDefault: `''`\n\nDefine an ID for the geosuggest. Needed when there are multiple instances on a page.\n\n#### className\n\nType: `String`\nDefault: `''`\n\nAdd an additional class to the geosuggest container.\n\n#### style\n\nType: `Object`\nDefault: `{\n  'input': {},\n  'suggests': {},\n  'suggestItem': {}\n}`\n\nAdd an additional style to `Geosuggest`.\nThis would support overriding/adding styles to the input suggestList and suggestItem.\n\n#### inputClassName\n\nType: `String`\nDefault: `''`\n\nAdd an additional class to the input.\n\n#### disabled\n\nType: `Boolean`\nDefault: `false`\n\nDefines whether the input is disabled.\n\n#### location\n\nType: [`google.maps.LatLng`](https://developers.google.com/maps/documentation/javascript/reference#LatLng)\nDefault: `null`\n\nTo get localized suggestions, define a location to bias the suggests.\n\n#### radius\n\nType: `Number`\nDefault: `0`\n\nThe radius in meters defines the area around the location to use for biasing the suggests. It must be accompanied by a `location` parameter.\n\n#### bounds\n\nType: [`LatLngBounds`](https://developers.google.com/maps/documentation/javascript/reference?csw=1#LatLngBounds)\nDefault: `null`\n\nThe bounds to use for biasing the suggests. If this is set, `location` and `radius` are ignored.\n\n#### country\n\nType: `String` or `Array`\nDefault: `null`\n\nRestricts 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.\n\n#### types\n\nType: `Array`\nDefault: `null`\n\nThe 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).\n\n#### fixtures\n\nType: `Array`\nDefault: `[]`\n\nAn 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.\n\nYou can also add a `className` key to a fixture. This class will be applied to the fixture item.\n\n#### maxFixtures\n\nType: `Number`\nDefault: `10`\n\nMaximum number of fixtures to render.\n\n#### placeDetailFields\n\nType: `Array`\nDefault: `null`\n\nBy 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.\n\n#### googleMaps\n\nType: `Object`\nDefault: `google.maps`\n\nIn case you want to provide your own Google Maps object, pass it in as googleMaps. The default is the global google maps object.\n\n#### ignoreTab\n\nType: `Boolean`\nDefault: `false`\n\nWhen the tab key is pressed, the `onSelect` handler is invoked. Set to true to not invoke `onSelect` on tab press.\n\n#### ignoreEnter\n\nType: `Boolean`\nDefault: `false`\n\nWhen the enter key is pressed, the `onSelect` handler is invoked. Set to true to not invoke `onSelect` on enter press.\n\n#### queryDelay\n\nType: `Number`\nDefault: `250`\n\nSets the delay in milliseconds after typing before a request will be sent to find suggestions.\nSpecify `0` if you wish to fetch suggestions after every keystroke.\n\n#### minLength\n\nType: `Number`\nDefault: `1`\n\nSets a minimum length of characters before a request will be sent to find suggestions.\n\n#### highlightMatch\n\nType: `Boolean`\nDefault: `true`\n\nHighlights matched text.\n\n#### onFocus\n\nType: `Function`\nDefault: `function() {}`\n\nGets triggered when the input field receives focus.\n\n#### onBlur\n\nType: `Function`\nDefault: `function(value) {}`\n\nGets triggered when input field loses focus.\n\n#### onChange\n\nType: `Function`\nDefault: `function(value) {}`\n\nGets triggered when input field changes the value.\n\n#### onKeyDown\n\nType: `Function`\nDefault: `function(event) {}`\n\nGets triggered when input field has a key pressed down. This event is triggered before onKeyPress.\n\n#### onKeyPress\n\nType: `Function`\nDefault: `function(event) {}`\n\nGets triggered when input field gets key press.\n\n#### onSuggestSelect\n\nType: `Function`\nDefault: `function(suggest) {}`\n\nGets triggered when a suggest got selected. Only parameter is an object with data of the selected suggest. This data is available:\n\n- `label` – Type `String` – The label name\n- `placeId` – Type `String` – If it is a preset, equals the `label`. Else it is the Google Maps `placeID`\n- `location` – Type `Object` – The location containing `lat` and `lng`\n- `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.\n\n#### onUpdateSuggests\n\nType: `Function`\nDefault: `function(suggests, activeSuggest) {}`\n\nGets 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.\n\n#### onActivateSuggest\n\nType: `Function`\nDefault: `function(suggest) {}`\n\nGets triggered when a suggest is activated in the list. Only parameter is an object with data of the selected suggest. This data is available:\n\n- `label` – Type `String` – The label name\n- `placeId` – Type `String` – If it is a preset, equals the `label`. Else it is the Google Maps `placeID`\n\n#### onSuggestNoResults\n\nType: `Function`\nDefault: `function(userInput) {}`\n\nGets triggered when there are no suggest results found\n\n#### getSuggestLabel\n\nType: `Function`\nDefault: `function(suggest) { return suggest.description; }`\n\nUsed 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.\n\n#### renderSuggestItem\n\nType: `Function`\nDefault: `null`\n\nUsed 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.\n\n#### skipSuggest\n\nType: `Function`\nDefault: `function(suggest) {}`\n\nIf 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)\n\n#### autoActivateFirstSuggest\n\nType: `Boolean`\nDefault: `false`\n\nAutomatically 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.\n\n#### label\n\nType: `String`\nDefault: `null`\n\nIf the `label` and a `id` prop (see \"Others\") were supplied, a `\u003clabel\u003e` tag with the passed label text will be rendered. The `\u003clabel\u003e` element's `for` attribute will correctly point to the `id` of the `\u003cinput\u003e` element.\n\n#### suggestsClassName\n\nType: `String`\nDefault: `''`\n\nAdd an additional class to suggest list.\n\n#### suggestsHiddenClassName\n\nType: `String`\nDefault: `null`\n\nAdditional `className` to toggle as the list of suggestions changes visibility.\n\n#### suggestItemClassName\n\nType: `String`\nDefault: `''`\n\nAdd an additional class to suggest item.\n\n#### suggestItemActiveClassName\n\nType: `String`,\nDefault: `null`\n\nAdditional `className` to add when a suggestion item is active.\n\n#### autoComplete\n\nType: `String`,\nDefault: `off`\n\nAutocomplete input attribute.\n\n#### inputType\n\nType: `String`,\nDefault: `text`\n\nThe value for the `type` attribute on the html input element. Can be either `text` or `search`.\n\n#### Others\n\nAll [allowed attributes for `input[type=\"text\"]`](https://github.com/ubilabs/react-geosuggest/blob/master/src/filter-input-attributes.ts#L4)\nAll [DOM clipboard events](https://facebook.github.io/react/docs/events.html#clipboard-events).\nAll [DOM mouse events](https://facebook.github.io/react/docs/events.html#mouse-events) except for drag \u0026 drop.\nAll [data attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/data-*).\n\n### Exposed component functions\n\nThese functions are accessible by setting \"ref\" on the component (see example below)\n\n#### focus()\n\nCall `focus` to focus on the element. The suggest list will be expanded with the current suggestions.\n\n#### blur()\n\nCall `blur` to blur (unfocus) the element. The suggest list will be closed.\n\n#### update(value)\n\nIt 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.\n\n#### clear()\n\nIt is also possible to clear the value of the input contained within the GeoSuggest component by calling the `clear` function.\n\n#### selectSuggest()\n\nSame effect as hitting `enter` (will geocode the text inside of the input).\n\n### Example\n\n```jsx\nimport React, {useRef} from 'react';\nimport ReactDOM from 'react-dom/client';\nimport Geosuggest from '@ubilabs/react-geosuggest';\n\nconst App = () =\u003e {\n  const geosuggestEl = useRef(null);\n\n  const fixtures = [\n    {label: 'New York', location: {lat: 40.7033127, lng: -73.979681}},\n    {label: 'Rio', location: {lat: -22.066452, lng: -42.9232368}},\n    {label: 'Tokyo', location: {lat: 35.673343, lng: 139.710388}}\n  ];\n\n  /**\n   * When a suggest got selected\n   */\n  const onSuggestSelect = (suggest) =\u003e console.log(suggest);\n\n  return (\n    \u003cdiv\u003e\n      \u003cGeosuggest\n        ref={geosuggestEl}\n        placeholder=\"Start typing!\"\n        initialValue=\"Hamburg\"\n        fixtures={fixtures}\n        onSuggestSelect={onSuggestSelect}\n        location={new google.maps.LatLng(53.558572, 9.9278215)}\n        radius=\"20\" /\u003e\n\n      {* Buttons to trigger exposed component functions *}\n      \u003cbutton onClick={()=\u003egeosuggestEl.current.focus()}\u003eFocus\u003c/button\u003e\n      \u003cbutton onClick={()=\u003egeosuggestEl.current.update('New Zealand')}\u003eUpdate\u003c/button\u003e\n      \u003cbutton onClick={()=\u003egeosuggestEl.current.clear()}\u003eClear\u003c/button\u003e\n      \u003cbutton onClick={()=\u003egeosuggestEl.current.selectSuggest()}\u003eSearch\u003c/button\u003e\n    \u003c/div\u003e\n  );\n};\n\nconst container = document.getElementById('app');\nconst root = ReactDOM.createRoot(container!);\nroot.render(\u003cApp /\u003e);\n```\n\n## Styling\n\nThis 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.\n\n### Note:\n\nThe `geosuggest__suggests--hidden` class is added to hide the suggestion list. You should copy the style below into your CSS file.\n\n```css\n.geosuggest__suggests--hidden {\n  max-height: 0;\n  overflow: hidden;\n  border-width: 0;\n}\n```\n\nThe 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.\n\nSimilarly, you need to have the class `geosuggest__item--active` similar to this:\n\n```css\n.geosuggest__item--active {\n  background: #267dc0;\n  color: #fff;\n}\n```\n\nto see what item is selected, f.ex. when using the arrow keys to navigate the suggestion list.\n\n## Contributing\n\nIssues and pull requests are welcome!\nPlease read the guidelines in [CONTRIBUTING.md](CONTRIBUTING.md) before starting to work on a PR.\n\n## License\n\nSee [LICENSE.md](LICENSE.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fubilabs%2Freact-geosuggest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fubilabs%2Freact-geosuggest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fubilabs%2Freact-geosuggest/lists"}