
Research
Security News
The Growing Risk of Malicious Browser Extensions
Socket researchers uncover how browser extensions in trusted stores are used to hijack sessions, redirect traffic, and manipulate user behavior.
places-autocomplete-js
Advanced tools
A flexible and customisable vanilla JavaScript library leveraging the Google Maps Places (New) Autocomplete API. This library provides a user-friendly way to search for and retrieve detailed address information in any web application.
A flexible and customizable vanilla JavaScript library leveraging the Google Maps Places (New) Autocomplete API. This library provides a user-friendly way to search for and retrieve detailed address information in any web application.
It handles API loading, session tokens for cost-effective usage, fetching suggestions with debouncing, keyboard navigation, highlighting matched text, and requesting place details, allowing you to focus on integrating the results into your application.
Explore interactive examples of the Google Places Autocomplete JS library:
A quick, editable sandbox to experiment with the core functionality:
See a more comprehensive live demo of the library in action: pacservice.pages.dev
onResponse
and onError
callbacks.requestParams
) and component behavior/appearance (options
).npm install places-autocomplete-js
# or
yarn add places-autocomplete-js
'___YOUR_API_KEY___'
with your actual Google Maps API Key.onResponse
callback to handle the response.<script>
import { PlacesAutocomplete } from 'places-autocomplete-js';
document.addEventListener('DOMContentLoaded', () => {
try {
const autocomplete = new PlacesAutocomplete({
containerId: 'autocomplete-container',
googleMapsApiKey: 'YOUR_GOOGLE_MAPS_API_KEY', // Replace with your actual key
onResponse: (placeDetails) => {
console.log('Place Selected:', placeDetails);
// Example: document.getElementById('address-field').value = placeDetails.formattedAddress;
// Example: document.getElementById('place-name').textContent = placeDetails.displayName;
},
onError: (error) => {
console.error('Autocomplete Error:', error.message || error);
}
});
// Optional: You can interact with the instance later
// autocomplete.clear();
// autocomplete.destroy(); // To clean up
} catch (error) {
console.error("Failed to initialize PlacesAutocomplete:", error.message);
}
});
</script>
...
<div id="autocomplete-container"></div>
...
The PlacesAutocomplete
class is initialized with a configuration object.
Parameter | Type | Required | Description |
---|---|---|---|
containerId | string | Yes | The ID of the HTML element where the autocomplete widget will be rendered. |
googleMapsApiKey | string | Yes | Your Google Maps API Key with the Places API (New) enabled. |
googleMapsApiVersion | string | No | The version of the Google Maps API to load (e.g., "weekly", "quarterly", "beta"). Defaults to "weekly". |
onResponse | function | No | Callback function triggered with selected place details. Receives a Place object (see Google's docs). Default logs to console. |
onError | function | No | Callback function triggered when an error occurs. Receives an Error object or string. Default logs to console. |
options | object | No | Object to customize UI behavior and appearance. See "UI & Behavior Options" below. |
requestParams | object | No | Object to customize the parameters sent to the Google Places Autocomplete API. See "API Request Parameters" below. |
fetchFields | array | No | Array of Place Data Fields to request when a place is selected. Affects API cost. Default ['formattedAddress', 'addressComponents'] |
options
)Passed within the main configuration object under the options
key.
Option | Type | Default | Description |
---|---|---|---|
placeholder | string | "Start typing your address ..." | Placeholder text for the input field. |
debounce | number | 100 | Delay in milliseconds before triggering an API request after user stops typing. Set to 0 to disable. |
distance | boolean | true | Whether to attempt to show distance in suggestions (requires origin in requestParams ). |
distance_units | 'km' | 'miles' | 'km' | Units to display distance in if distance is true. |
label | string | "" | Optional label text displayed above the input field. |
autofocus | boolean | false | If true , automatically focuses the input field on initialization. |
autocomplete | string | 'off' | Standard HTML autocomplete attribute for the input field. |
classes | object | (See default classes below) | Object to override default CSS classes for styling. See "Styling" section. |
clear_input | boolean | true | If true (default), clears the input field after a suggestion is selected. If false , the input field retains the formattedAddress of the selected place. |
requestParams
)Passed within the main configuration object under the requestParams
key. These parameters are sent to the Google Places Autocomplete API. Refer to the AutocompleteRequest documentation for all available options.
Common requestParams
:
input
: (string) Automatically handled by the library based on user typing.language
: (string) The language code, indicating in which language the results should be returned, if possible.region
: (string) The region code, specified as a ccTLD ("top-level domain") two-character value.includedRegionCodes
: (string[]) An array of up to 5 CLDR region codes to limit results to.locationBias
: (google.maps.places.LocationBias)locationRestriction
: (google.maps.places.LocationRestriction)origin
: (google.maps.LatLngLiteral) The origin point from which to calculate straight-line distances to predictions (if options.distance
is true).sessionToken
: Automatically managed by this library.Example requestParams
:
const autocomplete = new PlacesAutocomplete({
// ... other config
requestParams: {
language: 'fr',
region: 'ca',
includedRegionCodes: ['ca'],
origin: { lat: 45.5019, lng: -73.5674 } // Montreal
}
});
fetchFields
)The fetchFields
option allows you to specify which fields of place data you want to retrieve when a user selects a suggestion. This can help reduce API costs by only fetching the necessary information.
By default, the library fetches ['formattedAddress', 'addressComponents']
, but you can customize this based on your needs.
Example fetchFields
:
const autocomplete = new PlacesAutocomplete({
// ... other config
fetchFields: ['formattedAddress', 'addressComponents', 'displayName'] // Fetch additional fields as needed
});
To keep the selected address visible in the input field after a suggestion is chosen. Set the options.clear_input = false
.
const autocomplete = new PlacesAutocomplete({
// ... other config
options: {
clear_input: false // Retain the input value after selection
}
});
options.classes
)You can customize the appearance of the component by providing your own CSS classes via the options.classes
object. The library uses a default set of classes (many are Tailwind CSS utility classes but can be entirely replaced).
Provide an object where keys are the component parts and values are the class strings you want to apply.
Default Class Keys & Structure:
section
: The main container section.container
: The div containing the input and suggestions list.label
: The label element (if options.label
is provided).input
: The main text input element.icon_container
: Container for the optional icon.icon
: SVG string for the icon.ul
: The <ul>
element for the suggestions list.li
: Each <li>
suggestion item.li_current
: Class added to the currently highlighted/selected <li>
(keyboard/mouse).li_a
: The inner <a>
or <button>
element within each <li>
.li_a_current
: Class added to the inner element when its <li>
is current.li_div_container
: Container div within the <a>
/<button>
.li_div_one
: First inner div (usually contains the main text).li_div_one_p
: The <p>
tag containing the main suggestion text (@html
is used).li_div_two
: Second inner div (usually contains the distance).li_div_two_p
: The <p>
tag containing the distance text.kbd_container
: Container for the keyboard hint keys (Esc, Up, Down).kbd_escape
: The <kbd>
tag for the 'Esc' hint.kbd_up
: The <kbd>
tag for the 'Up Arrow' hint.kbd_down
: The <kbd>
tag for the 'Down Arrow' hint.highlight
: (New) The class applied to the <span>
wrapping the matched text within suggestions. Defaults to 'font-bold'
.Example: Overriding Classes
const autocomplete = new PlacesAutocomplete({
// ... other config
options: {
classes: {
input: 'my-custom-input form-control', // Replace default input style
ul: 'my-custom-dropdown-styles', // Custom dropdown style
li_current: 'my-active-suggestion', // Custom highlight for selected item
highlight: 'my-search-highlight' // Custom style for matched text
}
}
});
Then, style these classes in your CSS:
.my-custom-input {
padding: 10px;
border: 1px solid #ccc;
border-radius: 4px;
}
.my-search-highlight {
background-color: yellow;
color: black;
}
/* etc. */
Instances of PlacesAutocomplete
have the following public methods:
clear()
: Clears the input field and any visible suggestions, and refreshes the session token.destroy()
: Removes event listeners and cleans up DOM elements created by the widget. Useful when the component is no longer needed (e.g., in SPAs when a view is unmounted).displayName
, formattedAddress
, etc.) are billed separately. The library currently fetches displayName
, formattedAddress
, and addressComponents
by default. This can be expanded if needed, but be mindful of Place Data Fields Pricing.Contributions are welcome! Please feel free to open an issue or submit a pull request.
FAQs
A flexible and customisable vanilla JavaScript library leveraging the Google Maps Places (New) Autocomplete API. This library provides a user-friendly way to search for and retrieve detailed address information in any web application.
The npm package places-autocomplete-js receives a total of 102 weekly downloads. As such, places-autocomplete-js popularity was classified as not popular.
We found that places-autocomplete-js demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover how browser extensions in trusted stores are used to hijack sessions, redirect traffic, and manipulate user behavior.
Research
Security News
An in-depth analysis of credential stealers, crypto drainers, cryptojackers, and clipboard hijackers abusing open source package registries to compromise Web3 development environments.
Security News
pnpm 10.12.1 introduces a global virtual store for faster installs and new options for managing dependencies with version catalogs.