https://github.com/alexpechkarev/places-autocomplete-svelte
A flexible and customizable Svelte component leveraging the Google Maps Places (New) Autocomplete API to provide a user-friendly way to search for and retrieve detailed address information within your SvelteKit applications.
https://github.com/alexpechkarev/places-autocomplete-svelte
address-input autocomplete google-maps google-place-autocomplete google-places-api google-places-autocomplete-api svelte svelte-components sveltekit
Last synced: 5 days ago
JSON representation
A flexible and customizable Svelte component leveraging the Google Maps Places (New) Autocomplete API to provide a user-friendly way to search for and retrieve detailed address information within your SvelteKit applications.
- Host: GitHub
- URL: https://github.com/alexpechkarev/places-autocomplete-svelte
- Owner: alexpechkarev
- License: mit
- Created: 2024-07-20T11:22:35.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-06-07T11:30:23.000Z (21 days ago)
- Last Synced: 2025-06-17T06:43:53.123Z (11 days ago)
- Topics: address-input, autocomplete, google-maps, google-place-autocomplete, google-places-api, google-places-autocomplete-api, svelte, svelte-components, sveltekit
- Language: Svelte
- Homepage: https://places-autocomplete-demo.pages.dev/
- Size: 90.8 MB
- Stars: 7
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Places (New) Autocomplete Svelte
This Svelte component provides a user-friendly way to search for and retrieve detailed address information within your [SvelteKit](https://kit.svelte.dev) applications, leveraging the power of the [Google Maps Places (New) Autocomplete API](https://developers.google.com/maps/documentation/javascript/place-autocomplete-overview). It comes with default styling using [Tailwind CSS](https://tailwindcss.com/), which you can fully customise.
## Places (New) Autocomplete – JavaScript Integration
Simply include a single script tag and handle the response in your JavaScript code.
[View Details](https://pacservice.pages.dev/)
## Features
- **Seamless SvelteKit Integration:** Easily add the component to your SvelteKit projects.
- **Real-time Autocomplete Suggestions:** As the user types, address suggestions appear dynamically.
- **Comprehensive Address Details:** Retrieve detailed information, including street address, city, state/province, postal code, country, and more.
- **Country/Region Filtering:** Narrow down search results by specifying target countries or regions.
- **Customizable Styles:** Tailor the component's appearance to match your application's design by overriding the default Tailwind CSS classes.
- **Flexible Data Control:** Choose the specific data fields you want to retrieve using the `fetchFields` property.
- **Keyboard Navigation & Accessibility:** Use keyboard navigation for selecting suggestions, ensuring accessibility for all users.
## Demo
See a live demo of the component in action: [Basic Example](https://places-autocomplete-demo.pages.dev/)
[Reactive parameters](https://places-autocomplete-demo.pages.dev/examples/reactive-parameters) - change the search criteria based on user input, like filtering by country or change results language.
[Customise request parameters](https://places-autocomplete-demo.pages.dev/examples/customise-request-parameters) - construct a `requestParams` object and control various aspects of the search, including language, region, and more.
## Requirements
- **Google Maps API Key** with the Places API (New) enabled. Refer to [Use API Keys](https://developers.google.com/maps/documentation/javascript/get-api-key) for detailed instructions.
## Installation Svelte 5
```bash
npm i places-autocomplete-svelte
```
## Basic Usage
1. Replace `'___YOUR_API_KEY___'` with your actual **Google Maps API Key**.
2. Use the `onResponse` callback to **handle the response**.
```svelte
import { PlaceAutocomplete } from 'places-autocomplete-svelte';
//Recommended: Store your key securely as an environment variable
const PUBLIC_GOOGLE_MAPS_API_KEY = '___YOUR_API_KEY___';
let fullResponse = $state('')
let onResponse = (response) => {
fullResponse = response;
};
Response Object: {JSON.stringify(fullResponse, null, 2)}
```
## Component Properties
| Property | Type | Description | Required | Default Value |
|--------------------------|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|-----------------------------------------------|
| `PUBLIC_GOOGLE_MAPS_API_KEY` | `String` | Your Google Maps Places API Key. | Yes | |
| `onResponse` | `CustomEvent` | Dispatched when a place is selected, containing the place details in `event.detail`. | Yes | |
| `onError` | `CustomEvent` | Dispatched when an error occurs, with the error message in `event.detail`. | No | |
| `requestParams` | `Object` | Object for additional request parameters (e.g., `types`, `bounds`, `origin`, `region`, `language`). See [AutocompleteRequest](https://developers.google.com/maps/documentation/javascript/reference/autocomplete-data#AutocompleteRequest). | No | `{}` |
| `fetchFields` | `Array` | Array of place data fields to return. See [Supported Fields](https://developers.google.com/maps/documentation/javascript/place-class-data-fields) documentation for a comprehensive list of available fields. Note that the Places Autocomplete service does not support the following fields, even if they are available in the Place Details API: `geometry`, `icon`, `name`, `permanentlyClosed`, `photo`, `placeId`, `url`, `utcOffset`, `vicinity`, `openingHours`, `icon`, and `name`. If you need these fields, make a separate call to the Place Details API using the returned `place_id`. | No | `['formattedAddress', 'addressComponents']` |
| `options` | `Object` | Options for customizing the component's behavior and appearance. See "Customization" below. | No | See default values in "Customization" |
## Customization
### Options
| Property | Type | Description | Default Value |
|----------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
| `autofocus` | `boolean` | If `true`, the input field will be focused automatically when the component mounts. | `false` |
| `placeholder` | `String` | Placeholder text for the input field. | `"Search..."` |
| `autocomplete`| `string` | HTML `autocomplete` attribute for the input field. Set to `"off"` to disable browser autocomplete. | `"off"` |
| `distance`| `boolean` | If `true`, and if an `origin` is specified in `requestParams`, displays the distance to each suggestion. The distance is calculated as a geodesic in meters. | `false` |
| `distance_units`| `km` or `miles` | Specified the distance units. | `km` |
| `classes` | `Object` | Object to override default Tailwind CSS classes. | See [styling](https://places-autocomplete-demo.pages.dev/examples/styling) |
### Styling
Customise the component's appearance by providing an object to the classes property. This object should contain key-value pairs, where the keys correspond to the component's elements and the values are your custom CSS class names. See [styling](https://places-autocomplete-demo.pages.dev/examples/styling) for details.
### Request Parameters (requestParams)
Fine-tune the autocomplete search with the requestParams property. This property accepts an object corresponding to the AutocompleteRequest object in the Google Maps API documentation. See this [request parameters](https://places-autocomplete-demo.pages.dev/component/request-parameters) for more details. Here are some common examples:
```svelte
// ... other imports
/**
* @type object optional
* AutocompleteRequest properties
*/
const requestParams = {
/**
* @type string optional
*/
language : 'en-GB',
/**
* @type string optional
*/
region : 'GB',
}
/**
* @type object optional
* Options
*/
const options = {
autofocus: false,
autocompete: 'off',
placeholder: 'Start typing your address',
distance: true,
distance_units: 'km' // or miles
};
/**
* @type array optional
*/
const fetchFields = ['formattedAddress', 'addressComponents'];
```
## Error Handling
Use the `onError` event handler to gracefully manage any errors that may occur during the autocomplete process:
```svelte
// ... other imports
// Error handler
let pacError = '';
let onError = (error: string) => {
console.error(error);
pacError = error;
};
{#if pacError}
{pacError}
{/if}
```
## Contributing
Contributions are welcome! Please open an issue or submit a pull request on the [GitHub](https://github.com/alexpechkarev/places-autocomplete-svelte/).
## License
[MIT](LICENSE)