vue-geo-suggest
v1.0.2
Published
Renderless Vue component for finding addresses using Google Places API
Downloads
1,591
Maintainers
Readme
vue-geo-suggest
A small, renderless Vue component for finding addresses using Google Places API. The component simply provides a list of suggestions and place information as slot props in order to support custom UI and reduce size (2K gzipped). It is easily pluggable to Vuetify and other UI components.
This project was originally based on react-geosuggest
and vue-google-maps
.
Installation
npm install vue-geo-suggest
yarn add vue-geo-suggest
Apart from that, an API key is necessary for using Google Places. From the Google Developer Console's API Manager Dashboard, enable the following APIs:
Generate an API key and provide it to loadGmaps
utility.
The component and utilities can be imported directly:
import { GeoSuggest, loadGmaps } from 'vue-geo-suggest'
loadGmaps('my-api-key')
Vue.component(GeoSuggest.name, GeoSuggest) // Or register locally where needed
Or used as a plugin:
import GeoSuggest from 'vue-geo-suggest'
Vue.use(GeoSuggest, { apiKey: 'my-api-key' })
Usage
<GeoSuggest
:search="searchInput"
:suggestion="selectedSuggestion"
@geocoded="address = $event.normalizedAddress"
>
<template v-slot="{ suggestions, loading }">
<CustomSearchInput
v-model="searchInput"
/>
<CustomSuggestDropdown
v-model="selectedSuggestion"
:items="suggestions"
:loading="loading"
/>
</template>
</GeoSuggest>
import { GeoSuggest, loadGmaps } from 'vue-geo-suggest'
export default {
components: { GeoSuggest },
data() {
return {
searchInput: '', // Search text
selectedSuggestion: null, // Selected suggest from dropdown
address: null, // Information about the selected place
}
},
mounted() {
// Load API dependencies globally. This can be called any time
// before using GeoSuggest component.
// i.e. in `main.js` or directly in the view where is necessary.
loadGmaps('my-api-key')
},
}
Example with Vuetify:
<GeoSuggest
v-slot="{ suggestions, loading }"
:search="searchInput"
:suggestion="selectedSuggestion"
@geocoded="address = $event.normalizedAddress"
>
<VCombobox
v-model="selectedSuggestion"
:search-input.sync="searchInput"
:loading="loading"
:items="suggestions"
item-text="description"
no-filter
clearable
/>
</GeoSuggest>
API
geo-suggest
props
search
String (optional)Search string to filter places. A list of place suggestions with basic details will be provided based on this text. Example: "400 Broadway".
min-length
Number (optional)default: 3
Minimum length of the search string to trigger a request.
suggestion
Object (optional)Selected suggestion among all the provided values to show extended details about the place. This prop must be one of the elements inside the provided
suggestions
list. Containsdescription
,placeId
, andmatchedSubstrings
.debounce
Function (optional)Called whenever the
search
prop changes with another function as a single parameter that performs the actual request. Useful for debouncing requests with a custom query delay. Works directly withlodash.debounce
::debounce="fn => lodashDebounce(fn, msDelay)"
types
Array (optional)Filter suggestions by type. See types supported.
location
Object (optional)Allows localizing the resulting suggestions. See
google.maps.LatLng
.radius
Number (optional)Radius in meters that defines the valid area around the provided location. Must be used with
location
prop.bounds
Object (optional)Bounds for biasing the suggestions.
location
andradius
are ignored when using this. SeeLatLngBounds
.country
String|Array (optional)Restricts predictions to the specified countries (ISO 3166-1 Alpha-2 country code, case insensitive) Example:
'es'
;['it', 'fr']
.place-detail-fields
Array (optional)List of fields that should be returned by Google Places API. Useful to reduce the size of the response and optimize billing. All the fields are returned by default.
google-maps
Object|Function (optional)Google Maps object to use in case it is not loaded globally.
data
loading
true
when a request to Google Places API is pending. This is provided in the default scoped slot.suggestions
List of suggestions returned by Google Places API based on
search
. Each element is an object containingdescription
,placeId
andmatchedSubstrings
. This is provided in the default scoped slot.
events
suggestions
Fired when a new list of suggestions is returned by the Google Places API.
arguments:
suggestions
Array - List of suggestions.
error
Fired when Google Places API fails.
arguments:
payload.status
Object - The status returned.
geocoded
Fired when the selected suggestion is geocoded and all its details are available.
arguments:
payload.description
String - Same description string as in thesuggestions
list.payload.location
Object - Latitude (lat
) and longitude (lng
).payload.gmaps
Object - Complete response for this suggestion. See its structure here.payload.addressComponentsMap
Object - Handy structure that summarizesgmaps
components.payload.normalizedAddress
Object - Extended information based on the API result useful for shipping addresses.
Project setup for contributing
yarn # Installs dependencies
yarn dev # Compiles and hot-reloads for development
yarn build # Compiles and minifies for production
yarn lint # Lints and fixes files
yarn test:unit # Run tests
yarn doc:build # Update the API section of README.md