|
| 1 | +# Google Places Autocomplete |
| 2 | + |
| 3 | +A Vue component that provides Google Places Autocomplete functionality with a clean and customizable interface. |
| 4 | + |
| 5 | +## Usage |
| 6 | + |
| 7 | +```vue |
| 8 | +<script setup lang="ts"> |
| 9 | +import { GooglePlacesInputDemo } from 'ts-inputs-vue' |
| 10 | +import { ref } from 'vue' |
| 11 | +
|
| 12 | +const location = ref('') |
| 13 | +
|
| 14 | +function handlePlaceChanged(place: google.maps.places.PlaceResult) { |
| 15 | + console.log('Selected place:', place) |
| 16 | + // Access place.geometry.location for coordinates |
| 17 | + // Access place.formatted_address for the full address |
| 18 | +} |
| 19 | +</script> |
| 20 | +
|
| 21 | +<template> |
| 22 | + <GooglePlacesInputDemo |
| 23 | + v-model="location" |
| 24 | + api-key="YOUR_GOOGLE_MAPS_API_KEY" |
| 25 | + placeholder="Enter a location" |
| 26 | + @place-changed="handlePlaceChanged" |
| 27 | + /> |
| 28 | +</template> |
| 29 | +``` |
| 30 | + |
| 31 | +## Demo |
| 32 | + |
| 33 | +<GooglePlacesInputDemo /> |
| 34 | + |
| 35 | +## Props |
| 36 | + |
| 37 | +| Prop | Type | Default | Description | |
| 38 | +|------|------|---------|-------------| |
| 39 | +| `modelValue` | `string` | `''` | The v-model binding value | |
| 40 | +| `apiKey` | `string` | - | Your Google Maps API key (required) | |
| 41 | +| `placeholder` | `string` | `'Enter a location'` | Input placeholder text | |
| 42 | +| `disabled` | `boolean` | `false` | Whether the input is disabled | |
| 43 | +| `error` | `boolean` | `false` | Whether to show error state | |
| 44 | +| `types` | `string[]` | `['address']` | Array of place types to search for | |
| 45 | +| `componentRestrictions` | `{ country: string \| string[] }` | `{ country: 'us' }` | Country restrictions for search results | |
| 46 | + |
| 47 | +## Events |
| 48 | + |
| 49 | +| Event | Payload | Description | |
| 50 | +|-------|---------|-------------| |
| 51 | +| `update:modelValue` | `string` | Emitted when the input value changes | |
| 52 | +| `placeChanged` | `google.maps.places.PlaceResult` | Emitted when a place is selected, returns the full place details | |
| 53 | +| `blur` | `Event` | Emitted when the input loses focus | |
| 54 | + |
| 55 | +## Place Types |
| 56 | + |
| 57 | +You can specify different types of places to search for using the `types` prop. Common types include: |
| 58 | + |
| 59 | +- `'address'` - Addresses only |
| 60 | +- `'establishment'` - Business locations |
| 61 | +- `'geocode'` - Geocoded locations |
| 62 | +- `'(regions)'` - Cities, states, countries |
| 63 | +- `'(cities)'` - Cities only |
| 64 | + |
| 65 | +Example with multiple types: |
| 66 | + |
| 67 | +```vue |
| 68 | +<GooglePlacesInputDemo |
| 69 | + :types="['address', 'establishment']" |
| 70 | + api-key="YOUR_API_KEY" |
| 71 | +/> |
| 72 | +``` |
| 73 | + |
| 74 | +## Country Restrictions |
| 75 | + |
| 76 | +You can restrict results to specific countries using the `componentRestrictions` prop: |
| 77 | + |
| 78 | +```vue |
| 79 | +<GooglePlacesInputDemo |
| 80 | + :component-restrictions="{ country: ['us', 'ca'] }" |
| 81 | + api-key="YOUR_API_KEY" |
| 82 | +/> |
| 83 | +``` |
| 84 | + |
| 85 | +## Styling |
| 86 | + |
| 87 | +The component comes with default styling but can be customized using CSS. The following classes are available: |
| 88 | + |
| 89 | +- `.google-places-autocomplete` - The main container |
| 90 | +- `.suggestions` - The dropdown container |
| 91 | +- `.suggestion-item` - Individual suggestion items |
| 92 | +- `.suggestion-item--active` - Active/hovered suggestion item |
| 93 | + |
| 94 | +Example custom styling: |
| 95 | + |
| 96 | +```css |
| 97 | +.google-places-autocomplete { |
| 98 | + /* Custom styles */ |
| 99 | +} |
| 100 | + |
| 101 | +.suggestions { |
| 102 | + /* Custom dropdown styles */ |
| 103 | +} |
| 104 | + |
| 105 | +.suggestion-item { |
| 106 | + /* Custom suggestion item styles */ |
| 107 | +} |
| 108 | +``` |
| 109 | + |
| 110 | +## Google Maps API Setup |
| 111 | + |
| 112 | +1. Get a Google Maps API key from the [Google Cloud Console](https://console.cloud.google.com/) |
| 113 | +2. Enable the Places API for your project |
| 114 | +3. Add the API key to your component |
| 115 | + |
| 116 | +## Error Handling |
| 117 | + |
| 118 | +The component includes basic error handling for API requests. You can listen for errors in the console or implement your own error handling: |
| 119 | + |
| 120 | +```vue |
| 121 | +<script setup lang="ts"> |
| 122 | +function handleError(error: Error) { |
| 123 | + // Handle the error |
| 124 | + console.error('Google Places error:', error) |
| 125 | +} |
| 126 | +</script> |
| 127 | +
|
| 128 | +<template> |
| 129 | + <GooglePlacesInputDemo |
| 130 | + api-key="YOUR_API_KEY" |
| 131 | + @error="handleError" |
| 132 | + /> |
| 133 | +</template> |
| 134 | +``` |
| 135 | + |
| 136 | +## TypeScript Support |
| 137 | + |
| 138 | +The component is fully typed with TypeScript. You can import the types from the package: |
| 139 | + |
| 140 | +```typescript |
| 141 | +import type { AutocompletePrediction } from '@types/google.maps' |
| 142 | +``` |
0 commit comments