vue-easy-google-autocomplete
v1.0.0
Published
A simple and easy-to-use Vue 3 component for Google Places Autocomplete, with customizable hooks and debouncing.
Downloads
104
Maintainers
Readme
Google Places Autocomplete for Vue 3
A comprehensive Vue 3 library for integrating Google Places Autocomplete with options for both component-based and composition API (hook) usage. This tool allows users to efficiently search and select addresses, offering features like debouncing, language support, and customizable predictions.
Features
- Component and Hook Options: Use via a Vue component or a composition API hook for flexible integration.
- Easy Integration: Quickly integrate Google Places API for address autocomplete functionality.
- Debounced Search: Optimizes API calls, resulting in more efficient and responsive queries.
- Multi-language Support: Configure the API to support various languages.
- Customizable Predictions: Tailor the predictions based on types or country restrictions.
- Event Emission: Capable of emitting detailed information about selected places, which aids in form processing or data workflows.
Installation
Install the package with npm:
npm install vue-easy-google-autocomplete
Or using yarn:
yarn add vue-easy-google-autocomplete
Setup
To use the Google Places API, you need an API key from Google Cloud. Refer to this guide for obtaining your API key.
Usage
Component Usage
Here’s a basic example showcasing how to implement the GooglePlacesAutocomplete
component in a Vue 3 project:
<template>
<div>
<GooglePlacesAutocomplete
:apiKey="apiKey"
placeholder="Enter an address..."
language="en"
@place-selected="handlePlaceSelected"
/>
</div>
</template>
<script>
import { defineComponent } from 'vue';
import { GooglePlacesAutocomplete } from 'vue-easy-google-autocomplete';
export default defineComponent({
components: {
GooglePlacesAutocomplete,
},
data() {
return {
apiKey: 'YOUR_GOOGLE_API_KEY',
};
},
methods: {
handlePlaceSelected(placeDetails) {
console.log('Selected place details:', placeDetails);
},
},
});
</script>
Hook Usage
Alternatively, use the hook useGooglePlacesAutocomplete
for more granular control:
<template>
<div class="autocomplete-box">
<input
type="text"
v-model="query"
@input="fetchPredictions(query)"
:placeholder="placeholder"
/>
<ul v-if="predictions.length" class="suggestions-list">
<li
v-for="prediction in predictions"
:key="prediction.place_id"
@click="selectPlace(prediction)"
class="suggestion-item"
>
{{ prediction.description }}
</li>
</ul>
</div>
</template>
<script>
import { ref, defineComponent } from 'vue';
import { useGooglePlacesAutocomplete } from 'vue-easy-google-autocomplete';
export default defineComponent({
setup() {
const apiKey = 'YOUR_GOOGLE_API_KEY';
const {
predictions,
fetchPredictions,
fetchPlaceDetails,
resetPredictions,
} = useGooglePlacesAutocomplete(apiKey, {
debounceTime: 500,
predictionOptions: {
types: ['address'],
componentRestrictions: { country: 'br' },
},
language: 'en',
});
const query = ref('');
const selectPlace = async (prediction) => {
query.value = prediction.description;
const placeDetails = await fetchPlaceDetails(prediction.place_id);
console.log('Selected place details:', placeDetails);
resetPredictions();
};
return { query, predictions, fetchPredictions, selectPlace };
},
});
</script>
Props
apiKey
(required): Your Google Places API key.placeholder
(optional, default:"Enter an address..."
): Placeholder text for the input field.language
(optional, default:"en"
): Language code for Google Places API localization (e.g.,"pt-BR"
for Brazilian Portuguese).predictionOptions
(optional): Additional options to refine predictions, such as types or country restrictions.
Hook Options
debounceTime
: Milliseconds to debounce input queries.predictionOptions
: Options for the Google Places autocomplete query.libraries
: Libraries to load alongside the Google Maps API, default is['places']
.language
: Language for the API, default is'en'
.
Events
place-selected
: Triggered upon selecting an address, providing detailed place information.
Example with Options
Customizing the autocomplete service:
<template>
<GooglePlacesAutocomplete
:apiKey="apiKey"
language="pt-BR"
:predictionOptions="{
types: ['address'],
componentRestrictions: { country: 'br' },
}"
@place-selected="handlePlaceSelected"
/>
</template>
Debounce Support
Input is debounced by default at 300ms, adjustable with debounceTime
:
<template>
<GooglePlacesAutocomplete
:apiKey="apiKey"
:debounceTime="500" // Custom debounce time
@place-selected="handlePlaceSelected"
/>
</template>
API Key Restrictions
To enhance security, restrict your API key usage to specific referrer URLs within the Google Cloud Console settings.
Contributing ✨
Contributions to the JSnapCam are welcome! If you find any issues or have suggestions for improvements, feel free to open an issue or submit a pull request.
Thanks goes to these wonderful people (emoji key):
Development
To contribute or modify the library, follow these steps for local setup:
Clone the repository:
git clone https://github.com/iguilhermeluis/vue-easy-google-autocomplete.git
Install dependencies:
npm install
Run the development server:
npm run dev
License
This project is licensed under the MIT License, promoting open-source use and contribution.