From 08115cb147b2ff572dbe8d6ebd0a88edec59900b Mon Sep 17 00:00:00 2001 From: Leslie Zimmermann Date: Mon, 7 Aug 2023 14:40:05 +0200 Subject: [PATCH] docs(README): add new npm package scope to README --- README.md | 84 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 66 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index f7cc97d..48a9d32 100644 --- a/README.md +++ b/README.md @@ -2,19 +2,17 @@ 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 - - + + … @@ -32,7 +30,7 @@ The easiest way to use geosuggest is to install it from NPM and include it in yo 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 react-geosuggest --save +npm install @ubilabs/react-geosuggest --save ``` ## Usage @@ -42,46 +40,51 @@ The Geosuggest works out of the box by just including it. However, you can custo ### ES6: ```js -import Geosuggest from 'react-geosuggest'; +import Geosuggest from '@ubilabs/react-geosuggest'; - +; ``` ### ES5: ```js -var Geosuggest = require('react-geosuggest').default; +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': {}, @@ -93,48 +96,56 @@ 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: `[]` @@ -143,36 +154,42 @@ An array with fixtures (defaults). Each fixture has to be an object with a `labe 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` @@ -180,140 +197,162 @@ Sets the delay in milliseconds after typing before a request will be sent to fin 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. +- `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 react-geosuggest. +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` +- `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 `