New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More →

@placekit/autocomplete-js

Package Overview

Dependencies

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

@placekit/autocomplete-js

PlaceKit Autocomplete JavaScript library

1.2.0
Source
npm

Version published: 2 years ago

Weekly downloads: 434; decreased by-6.47%

Maintainers: 2

Weekly downloads

Created: 2 years ago

Source

PlaceKit Autocomplete JS Library

All-in-one address autocomplete experience for your web apps

Quick start • Features • Reference • Customize • License

PlaceKit Autocomplete JavaScript Library is a standalone address autocomplete field for your application, built on top of our PlaceKit JS client. Under the hood it relies on Popper to position the suggestions list, and on Flagpedia to display flags on country results.

If you already use a components library with an autocomplete field, or need a more advanced usage, please refer to our PlaceKit JS client reference and its examples.

For React implementations, check our PlaceKit Autocomplete React library. And for Vue implementations, check our Vue.js example.

✨ Features

Standalone and lightweight: about 12kb of JS, and 4kb of CSS, gzipped
Cross browser: compatible across all major modern browsers
Non-invasive: use and style your own input element
Customizable and extensible with events and hooks
TypeScript compatible
W3C WAI compliant

🎯 Quick start

CDN

First, import the library and the default stylesheet into the <head> tag in your HTML:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@placekit/autocomplete-js@1.1.5/dist/placekit-autocomplete.min.css" />
<script src="https://cdn.jsdelivr.net/npm/@placekit/autocomplete-js@1.1.5"></script>

After importing the library, placekitAutocomplete becomes available as a global:

<input type="search" placeholder="Search place..." class="pka-input" id="placekit" />
<script>
  const pka = placekitAutocomplete('<your-api-key>', {
    target: '#placekit',
    countries: ['fr'],
    // other options...
  });
</script>

Or if you are using native ES Modules:

<script type="module">
  import placekit from 'https://cdn.jsdelivr.net/npm/@placekit/autocomplete-js@1.1.5/dist/placekit-autocomplete.esm.js';
  const pka = placekitAutocomplete(/* ... */);
  // ...
</script>

NOTE: Make sure to call placekitAutocomplete after the DOM is loaded so the input can be found.

NPM

First, install PlaceKit Autocomplete using npm package manager:

npm install --save @placekit/autocomplete-js

Then import the package and perform your first address search:

// CommonJS syntax:
const placekitAutocomplete = require('@placekit/autocomplete-js');

// ES6 Modules syntax:
import placekit from '@placekit/autocomplete-js';

const pka = placekitAutocomplete('<your-api-key>', {
  target: '#placekit',
  countries: ['fr'],
  // other options...
});

Don't forget to import @placekit/autocomplete-js/dist/placekit-autocomplete.css if you want to use our default style. If you have trouble importing CSS from node_modules, copy/paste its content into your own CSS.

👉 Check out our examples for different use cases!

🧰 Reference

`placekitAutocomplete()`

PlaceKit Autocomplete initialization function returns a PlaceKit Autocomplete client, named pka in all examples.

const pka = placekitAutocomplete('<your-api-key>', {
  target: '#placekit',
  countries: ['fr'],
  maxResults: 10,
});

Parameter	Type	Description
`apiKey`	`string`	API key
`options`	`key-value mapping` (optional)	Global parameters (see options)

`pka.input`

Input field element passed as target option, read-only.

console.log(pka.input); // <input ... />

`pka.options`

Options from both PlaceKit Autocomplete and PlaceKit JS client, read-only.

console.log(pka.options); // { "target": <input ... />, "language": "en", "maxResults": 10, ... }

Option	From	Type	Default	Description
`target`	AutoComplete	`string\|Element`	`-`	Target input element or (unique) selector.
`offset`	AutoComplete	`integer`	`4`	Gap between input and suggestions list in pixels.
`template`	AutoComplete	`(item: object) => string`	see index.js	Suggestion item formatting function.
`formatValue`	AutoComplete	`(item: object) => string`	see index.js	Input value formatting function when selected from list.
`noResults`	AutoComplete	`string\|(query: string) => string`	see index.js	No result template.
`strategy`	AutoComplete	`'absolute'	'fixed'`	`absolute`
`flip`	AutoComplete	`boolean`	`false`	Flip position top when overflowing.
`className`	AutoComplete	`string`	`undefined`	Additional suggestions panel CSS class(es).
`maxResults`	JS client	`integer`	`5`	Number of results per page.
`language`	`string?`	`undefined`	Preferred language for the results⁽¹⁾, two-letter ISO language code. Supported languages are `en` and `fr`. Defaults to the country's language.
`types`	JS client	`string[]?`	`undefined`	Type of results to show. Array of accepted values: `street`, `city`, `country`, `airport`, `bus`, `train`, `townhall`, `tourism`. Prepend `-` to omit a type like `['-bus']`. Unset to return all.
`countries`	`string[]?`	`undefined`	Countries to search in, or fallback to if `countryByIP` is `true`. Array of two-letter ISO country codes⁽¹⁾.
`countryByIP`	`boolean?`	`undefined`	Use IP to find user's country (turned off).
`coordinates`	JS client	`string?`	`undefined`	Coordinates to search around. Automatically set when calling `pka.requestGeolocation()`.

[1]: See Scope and Limitations for more details.

⚠️ `countries` option is required

The countries option is required at search time, but we like to keep it optional across all methods so developers remain free on when and how to define it:

either when instanciating with placekit(),
with pk.configure(),
or at search time with pk.search().

If countries is missing or invalid, you'll get a 422 error, excepted whentypes option is set to ['country'] only.

`countryByIP` option

Set countryByIP to true when you don't know which country users will search addresses in. In that case, the option countries will be used as a fallback if the user's country is not supported:

pka.configure({
  countryByIP: true, // use user's country, based on their IP
  countries: ['fr', 'be'], // returning results from France and Belgium if user's country is not supported
});

`pka.configure()`

Updates search parameters (only JS client options!). Returns the instance so you can chain methods.

pka.configure({
  language: 'fr',
  maxResults: 5,
});

Parameter	Type	Description
`opts`	`key-value mapping` (optional)	Global parameters (see options)

`pka.state`

Read-only object of input state.

console.log(pka.state); // {dirty: false, empty: false, freeForm: true}

// `true` after the user modifies the input value.
console.log(pka.state.dirty); // true or false

// `true` whenever the input value is not empty.
console.log(pka.state.empty); // true or false

// `true` if the input has a free form value or `false` if value is selected from the suggestions.
console.log(pka.state.freeForm); // true or false

The freeForm value comes handy if you need to implement a strict validation of the address, but we don't interfere with how to implement it as input validation is always very specific to the project's stack.

`pka.on()`

pka.on('open', () => {})
  .on('close', () => {})
  .on('results', (query, results) => {})
  .on('pick', (value, item, index) => {})
  .on('error', (error) => {})
  .on('dirty', (dirty) => {})
  .on('empty', (empty) => {})
  .on('freeForm', (freeForm) => {})
  .on('state', (state) => {})
  .on('geolocation', (hasGeolocation, position) => {});

If you register a same event twice, the first one will be replaced. So, to remove an handler, simply assign undefined:

pka.on('open'); // clears handler for 'open' event

Events

`open`

Triggered when panel opens.

`close`

Triggered when panel closes.

`results`

Triggered when suggestions list gets updated, same as when the user types or enables geolocation.

Parameter	Type	Description
`query`	`string`	Input value.
`results`	`object[]`	Results returned from API.

`pick`

Triggered when user selects an item from the suggestion list by clicking on it or pressing ENTER after using the keyboard navigation.

Parameter	Type	Description
`value`	`string`	Input value (value returned by `options.formatValue()`).
`item`	`object`	All item details returned from API.
`index`	`number`	Position of the selected item in the suggestions list, zero-based.

`error`

Triggered on server error.

Parameter	Type	Description
`error`	`object`	Error details.

`dirty`

Triggered when the input value changes.

Parameter	Type	Description
`dirty`	`boolean`	`true` after the user modifies the value.

`empty`

Triggered when input value changes.

Parameter	Type	Description
`empty`	`boolean`	`true` if input is empty.

`freeForm`

Triggered when input value changes.

Parameter	Type	Description
`freeForm`	`boolean`	`true` on user input, `false` on `pick` event.

`state`

Triggered when one of the input states changes.

Parameter	Type	Description
`state`	`object`	The current input state.

`geolocation`

Triggered when hasGeolocation value changes (a.k.a. when pka.requestGeolocation is called).

Parameter	Type	Description
`hasGeolocation`	`boolean`	`true` if granted, `false` if denied.
`position`	`GeolocationPosition`	Passed when `hasGeolocation` is `true`.

`pka.handlers`

Reads registered event handlers, read-only.

pka.on('open', () => {});
console.log(pka.handlers); // { open: ... }

`pka.requestGeolocation()`

Requests device's geolocation (browser-only). Returns a Promise with a GeolocationPosition object.

pka.requestGeolocation({ timeout: 10000 }).then((pos) => console.log(pos.coords));

Parameter	Type	Description
`opts`	`key-value mapping` (optional)	`navigator.geolocation.getCurrentPosition` options
`cancelUpdate`	`boolean` (optional)	If `false` (default), suggestions list updates immediately based on device location.

The location will be store in the coordinates global options, you can still manually override it.

`pka.hasGeolocation`

Reads if device geolocation is activated or not (read-only).

console.log(pka.hasGeolocation); // true or false

`pka.open()`

Opens the suggestion panel.

pka.open();

`pka.close()`

Closes the suggestion panel.

pka.close();

`pka.clear()`

Clears the input value, focus the field, and closes the suggestion panel.

pka.clear();

`pka.destroy()`

Removes the suggestions panel from the DOM and clears all event handlers from window and input that were added by PlaceKit Autocomplete.

pka.destroy();

💅 Customize

You have full control over the input element as PlaceKit Autocomplete doesn't style nor alter it by default. We still provide a style that you can apply by adding the .pka-input class to your input element.

Colors, border-radius, font and overall scale (in rem) are accessible over variables:

:root {
  --pka-scale: 1rem;
  --pka-color-accent: 1, 73, 200;
  --pka-color-black: 29, 41, 57;
  --pka-color-darker: 52, 64, 84;
  --pka-color-dark: 152, 162, 179;
  --pka-color-light: 207, 213, 221;
  --pka-color-lighter: 243, 244, 246;
  --pka-color-white: 255, 255, 255;
  --pka-border-radius: 6px;
  --pka-font-family: system-ui, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
  --pka-z-index: 9999;
}

/* dark mode overrides */
body.dark,
body[data-theme="dark"] {
  --pka-color-accent: 55, 131, 249;
}

For advanced customization, refer to our stylesheet to learn about the available classes if you need to either override some or start a theme from scratch.

A dark mode is available whenever you add .dark class or data-theme="dark" attribute to the <body> element.

⚠️ NOTE: you are not allowed to hide the PlaceKit logo unless we've delivered a special authorization. To request one, please contact us using our contact form.

⚖️ License

PlaceKit Autocomplete JS Library is an open-sourced software licensed under the MIT license.

FAQs

What is @placekit/autocomplete-js?

Is @placekit/autocomplete-js popular?

Is @placekit/autocomplete-js well maintained?

Package last updated on 06 Jun 2023

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.

Install

@placekit/autocomplete-js

PlaceKit Autocomplete JS Library

✨ Features

🎯 Quick start

CDN

NPM

🧰 Reference

placekitAutocomplete()

pka.input

pka.options

⚠️ countries option is required

countryByIP option

pka.configure()

pka.state

pka.on()

Events

open

close

results

pick

error

dirty

empty

freeForm

state

geolocation

pka.handlers

pka.requestGeolocation()

pka.hasGeolocation

pka.open()

pka.close()

pka.clear()

pka.destroy()

💅 Customize

⚖️ License

Related posts

CISA Brings KEV Data to GitHub

Opengrep Emerges as Open Source Alternative Amid Semgrep Licensing Controversy

`placekitAutocomplete()`

`pka.input`

`pka.options`

⚠️ `countries` option is required

`countryByIP` option

`pka.configure()`

`pka.state`

`pka.on()`

`open`

`close`

`results`

`pick`

`error`

`dirty`

`empty`

`freeForm`

`state`

`geolocation`

`pka.handlers`

`pka.requestGeolocation()`

`pka.hasGeolocation`

`pka.open()`

`pka.close()`

`pka.clear()`

`pka.destroy()`