Places (New) Autocomplete Svelte

A flexible, accessible, and secure Svelte component leveraging the Google Maps Places Autocomplete API (New). Winner of the Google Maps Platform Awards 2025, recognising excellence in Google Maps Platform development.

The component handles API loading, session tokens, debounced fetching, and accessibility, allowing you to focus on building your application. It intelligently manages the Google Maps API loader, creating a shared instance via Svelte's context that prevents conflicts with other map components on the same page.

Two initialisation patterns:

• Simple/Automatic: Pass your API key directly to the component for basic use cases
• Advanced/Manual: Initialise the loader once in a parent component when using multiple Google Maps libraries or components

Table of Contents

• Features
• Demo
• Recognition
• Requirements
• Installation
• Usage
  • Basic Usage
  • Advanced Usage
• Props
• Component Methods
• Options
• Styling
• Events
• TypeScript
• Security
• Accessibility
• Google Places API & Billing
• Standalone JavaScript Library
• Contributing
• License

Features

Core Functionality

• 🗺️ Integrates with the modern Google Maps Places Autocomplete API (New)
• 🔄 Automatic Shared Loader: Intelligently creates a single Google Maps loader instance and shares it via Svelte's context
• 💰 Automatically handles session tokens for optimal cost management
• ⚡ Debounced Input: Configurable delay to minimise API calls while typing
• ✨ Suggestion Highlighting: Automatically highlights matched text in suggestions

Accessibility & User Experience

• ♿ WCAG Compliant: Follows WAI-ARIA patterns for comboboxes
• ⌨️ Full Keyboard Navigation: Arrow keys, Enter, and Escape support
• 📢 Screen Reader Support: Proper ARIA attributes for assistive technologies

Developer Experience

• 🎨 Customisable Styling: Override default styles via options.classes prop
• 🔧 Imperative API: Direct control with clear(), focus(), getRequestParams(), setRequestParams(), setFetchFields(), and getFetchFields() methods
• 📘 TypeScript Support: Fully typed with comprehensive type definitions
• 🔐 Secure: XSS protection with safe rendering of suggestions
• 🎯 Event Handling: onResponse and onError callbacks for complete control

Demo

Explore live examples showcasing different features and use cases:

🚀 Basic Example - Get started with the simplest implementation

🔄 Reactive Parameters - Dynamically change search criteria based on user input, such as filtering by country or switching languages

⚙️ Custom Request Parameters - Configure advanced search options including language, region, location bias, and place types

📝 Retain Input Value - Keep the selected address visible in the input field after selection

Recognition

🏆 Google Maps Platform Awards 2025 Winner

This component has been recognised as a winner of the Google Maps Platform Awards 2025 by the Google Developer Program. This award celebrates outstanding projects that demonstrate exceptional use of Google Maps Platform APIs, innovation, and contribution to the developer community.

Learn more about the Google Maps Platform Awards

Requirements

• Google Maps API Key with the "Places API" enabled. Refer to Use API Keys for detailed instructions.

Installation

npm install places-autocomplete-svelte
# or
yarn add places-autocomplete-svelte

Usage

Basic Usage (Automatic Initialisation)

For simple use cases, just pass your API key to the component. It will automatically handle the Google Maps loader initialisation:

<script lang="ts">
    import { PlaceAutocomplete } from 'places-autocomplete-svelte';
    import type { PlaceResult } from 'places-autocomplete-svelte/interfaces';

    // Get API Key securely (e.g., from environment variables)
    const PUBLIC_GOOGLE_MAPS_API_KEY = import.meta.env.VITE_PUBLIC_GOOGLE_MAPS_API_KEY;

    const handleResponse = (response: PlaceResult) => {
        console.log('Selected:', response.formattedAddress);
    };

    const handleError = (error: string) => {
        console.error('Error:', error);
    };
</script>

<PlaceAutocomplete 
    {PUBLIC_GOOGLE_MAPS_API_KEY}
    onResponse={handleResponse} 
    onError={handleError} 
/>

Advanced Usage (Manual Initialisation)

For applications using multiple Google Maps libraries (e.g., places, maps, marker) or multiple map components, initialise the loader once in a parent component.

Benefits:

• ✅ Loads all required libraries in a single API call (more efficient)
• ✅ Prevents "Loader must not be called again" errors
• ✅ Shares the loader instance across all child components via Svelte context
• ✅ Works seamlessly with SvelteKit's SSR (only initialises in the browser)

When to use manual initialisation:

• Multiple Google Maps components on the same page
• Multiple libraries needed (maps, marker, geometry, etc.)
• Shared map functionality across routes
• Centralised error handling for the loader

// In +layout.svelte or +page.svelte
<script lang="ts">
    import { browser } from '$app/environment';
    import { PlaceAutocomplete } from 'places-autocomplete-svelte';
    import { setGMapsContext, initialiseGMaps, importLibrary } from 'places-autocomplete-svelte/gmaps';
    import { onMount } from 'svelte';
    import type { PlaceResult } from 'places-autocomplete-svelte/interfaces';

    // 1. Set the context at the top level (must be synchronous)
    setGMapsContext();

    // 2. Initialise the loader in the browser
    if (browser) {
        initialiseGMaps({
            key: import.meta.env.VITE_PUBLIC_GOOGLE_MAPS_API_KEY,
            v: 'weekly'
        }).catch((error) => {
            console.error('Failed to initialise Google Maps:', error);
        });
    }

    // 3. Load additional libraries as needed
    let map: google.maps.Map;
    
    onMount(async () => {
        const { Map } = await importLibrary('maps');
        const mapElement = document.getElementById('map');
        if (mapElement) {
            map = new Map(mapElement, {
                center: { lat: 51.5072, lng: -0.1276 },
                zoom: 10,
                mapId: 'YOUR_MAP_ID'
            });
        }
    });

    // 4. Handle autocomplete responses
    const handleResponse = (response: PlaceResult) => {
        console.log('Selected:', response.formattedAddress);
        if (response.location && map) {
            map.setCenter(response.location);
            map.setZoom(15);
        }
    };

    const handleError = (error: string) => {
        console.error('Error:', error);
    };
</script>

<!-- The component automatically uses the shared context -->
<!-- No need to pass PUBLIC_GOOGLE_MAPS_API_KEY when using manual initialisation -->
<PlaceAutocomplete 
    onResponse={handleResponse} 
    onError={handleError} 
/>

<div id="map" class="h-96 w-full"></div>

Available helper functions from places-autocomplete-svelte/gmaps:

• setGMapsContext() - Creates the shared context (call once at the top level)
• getGMapsContext() - Retrieves the context (returns stores for initialisation state and errors)
• hasGMapsContext() - Checks if context exists (useful for conditional logic)
• initialiseGMaps(options) - Initialises the loader with your API key and options
• initialiseGMapsNoContext(options) - Initialises without context (for edge cases)
• importLibrary(library) - Dynamically imports Google Maps libraries

Security

API Key Security

Your Google Maps API Key is a sensitive credential. To prevent unauthorised use and unexpected charges, you must restrict it.

1. Go to the Google Cloud Console.
2. Select your API key.
3. Under Application restrictions, select HTTP referrers (web sites) and add your application's domain(s) (e.g., your-domain.com/*).
4. Under API restrictions, select Restrict key and choose the APIs you are using (e.g., Places API, Maps JavaScript API).

XSS Protection

This component is designed to be secure out-of-the-box. It safely renders user-input and API responses to prevent Cross-Site Scripting (XSS) vulnerabilities.

Accessibility

This component is built to be accessible and follows the WAI-ARIA Authoring Practices for a Combobox.

• Keyboard Navigation: Users can navigate suggestions using ArrowUp, ArrowDown, select with Enter, and close the list with Escape.
• Screen Reader Support: Uses role="combobox", aria-autocomplete, aria-expanded, and aria-activedescendant to provide a clear experience for screen reader users.
• Focus Management: Focus remains on the input field while navigating the suggestion list.

Props

*Either PUBLIC_GOOGLE_MAPS_API_KEY prop OR manual initialisation with initialiseGMaps() is required.

Component Methods (Imperative API)

Get a reference to the component instance using bind:this to call its methods directly.

Example:

<script lang="ts">
    import PlaceAutocomplete from 'places-autocomplete-svelte';
    let autocompleteComponent: PlaceAutocomplete | undefined = $state(undefined);
</script>

<PlaceAutocomplete bind:this={autocompleteComponent} ... />

<button onclick={() => autocompleteComponent?.clear()}>Clear</button>
<button onclick={() => autocompleteComponent?.focus()}>Focus</button>
<button onclick={() => autocompleteComponent?.setRequestParams({ region: 'FR', language: 'fr' })}>
    Switch to French
</button>
<button onclick={() => autocompleteComponent?.setOptions({ placeholder: 'Search locations...', debounce: 300 })}>
    Update Options
</button>

Options

Styling

Default Styles

The component includes built-in styles with .pac- prefixed CSS classes, providing a complete, accessible UI out of the box. These styles are:

• Framework-agnostic: Pure CSS with no dependencies on Tailwind or other frameworks
• Modern design: Clean, professional appearance with proper spacing, shadows, and hover effects
• Fully functional: Includes keyboard navigation indicators, loading states, and responsive behavior
• Customisable: All styles can be overridden via the options.classes prop

The default styles include:

• Rounded input with shadow and focus states
• Dropdown list with scroll behavior and dividers
• Keyboard navigation hints (Esc, ↑, ↓)
• Highlighted current selection with color transitions
• Distance display for location-based results
• Icon support with proper alignment
• Responsive layout for mobile and desktop

Customisation (options.classes)

Override any default styling by providing your own CSS classes via options.classes. Your custom classes will replace the default .pac- classes for the specified elements.

Available Class Keys:

• section: The main container section (default: .pac-section)
• container: The div containing the input and suggestions list (default: .pac-container)
• label: The label element
• input: The main text input element (default: .pac-input)
• icon_container: Container for the optional icon (default: .pac-icon-container)
• icon: SVG string for the icon
• ul: The <ul> element for the suggestions list (default: .pac-ul)
• li: Each <li> suggestion item (default: .pac-li)
• li_current: Class added to the currently highlighted <li> (default: .pac-li-current)
• li_button: The <button> within each list item (default: .pac-li-button)
• li_button_current: Class added to the currently highlighted button (default: .pac-li-button-current)
• li_div_container: Container div within each list item (default: .pac-li-div-container)
• li_div_one: First inner div containing the main text (default: .pac-li-div-one)
• li_div_one_p: The <p> tag containing the main suggestion text (default: .pac-li-div-one-p)
• li_div_one_p_secondaryText: The <p> tag for secondary text (default: .pac-li-div-one-p-secondaryText)
• li_div_p_container: Container for paragraphs (default: .pac-li-div-p-container)
• li_div_two: Second inner div containing the distance (default: .pac-li-div-two)
• li_div_two_p: The <p> tag containing the distance text (default: .pac-li-div-two-p)
• kbd_container: Container for the keyboard hint keys (default: .pac-kbd-container)
• kbd_escape: The <kbd> tag for the 'Esc' hint (default: .pac-kbd-escape)
• kbd_up: The <kbd> tag for the 'Up Arrow' hint (default: .pac-kbd-up)
• kbd_down: The <kbd> tag for the 'Down Arrow' hint (default: .pac-kbd-down)
• kbd_active: Class applied to active keyboard hints (default: .pac-kbd-active)
• map_pin_icon: SVG string for the map pin icon
• highlight: The class applied to the <span> wrapping the matched text (default: .pac-highlight)

Example - Using with Tailwind CSS:

const options = {
  classes: {
    input: 'w-full px-4 py-2.5 border border-gray-300 rounded-md focus:ring-2 focus:ring-blue-500',
    ul: 'absolute mt-1 w-full bg-white shadow-lg rounded-md border border-gray-200 max-h-60 overflow-auto',
    li: 'px-4 py-2 hover:bg-blue-500 hover:text-white cursor-pointer',
    li_current: 'bg-blue-500 text-white',
    highlight: 'font-semibold text-blue-700'
  }
};

Example - Using with Custom CSS:

const options = {
  classes: {
    section: 'autocomplete-wrapper',
    input: 'search-input',
    ul: 'suggestions-list',
    li: 'suggestion-item',
    li_current: 'suggestion-item--active'
  }
};

Events

• onResponse: (response: PlaceResult) => void
  • Fired after a user selects a suggestion and fetchFields are retrieved.
• onError: (error: string) => void
  • Fired on any error (API loading, fetching suggestions, etc.).

TypeScript

This component is fully written in TypeScript with comprehensive type definitions.

Available Imports

Component:

import { PlaceAutocomplete } from 'places-autocomplete-svelte';

Types and Interfaces:

import type { 
    PlaceResult,       // Place data returned from API
    ComponentOptions,  // UI and behavior configuration
    RequestParams,     // Autocomplete request parameters
    FormattedAddress,  // Standardised address structure
    ComponentClasses,  // CSS class overrides
    Props              // Component props
} from 'places-autocomplete-svelte/interfaces';

Google Maps Loader Helpers:

import { 
    setGMapsContext,           // Create shared context
    getGMapsContext,           // Retrieve context
    hasGMapsContext,           // Check if context exists
    initialiseGMaps,           // Initialise with context
    initialiseGMapsNoContext,  // Initialise standalone
    importLibrary,             // Load Google Maps libraries
    type GMapsContext,         // Context type
    type APIOptions            // Loader options type
} from 'places-autocomplete-svelte/gmaps';

Security

• This component uses the Google Maps JavaScript API (Places library). Usage is subject to Google's terms and pricing.
• Session Tokens are used automatically to group Autocomplete requests, which can reduce costs.
• Place Details requests (via fetchFields) are billed separately. Only request the fields you need to manage costs effectively.
• For detailed pricing information, see Google Maps Platform Pricing.

Standalone JavaScript Library

Need this functionality for a non-Svelte project? Check out our companion vanilla JavaScript library:

places-autocomplete-js - Same core Google Places (New) Autocomplete features, framework-agnostic implementation.

Contributing

Contributions are welcome! We appreciate bug reports, feature requests, and pull requests.

How to contribute:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure your code follows the existing style and includes appropriate tests.

Author

Alexander Pechkarev

• GitHub: @alexpechkarev
• Email: alexpechkarev@gmail.com

License

This project is licensed under the MIT License - see the LICENSE file for details.

_{Built with ❤️ using Svelte 5 and Google Maps Platform}