New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More →
@placekit/autocomplete-js
Advanced tools
@placekit/autocomplete-js - npm Package Compare versions
to
2.1.7
@@ -1,2 +0,2 @@ | ||
| /*! @placekit/autocomplete-js v2.1.6 | © placekit.io | MIT license | https://github.com/placekit/autocomplete-js#readme */ | ||
| /*! @placekit/autocomplete-js v2.1.7 | © placekit.io | MIT license | https://github.com/placekit/autocomplete-js#readme */ | ||
| import type { PKOptions, PKResult } from '@placekit/client-js'; | ||
@@ -78,2 +78,2 @@ | ||
| countrySelect?: boolean; | ||
| }; | ||
| }; |
| { | ||
| "name": "@placekit/autocomplete-js", | ||
| "version": "2.1.6", | ||
| "version": "2.1.7", | ||
| "author": "PlaceKit <support@placekit.io>", | ||
@@ -40,3 +40,3 @@ "description": "PlaceKit Autocomplete JavaScript library", | ||
| "lint": "eslint ./src", | ||
| "format": "eslint ./src --fix" | ||
| "format": "prettier --write ./src" | ||
| }, | ||
@@ -48,6 +48,8 @@ "devDependencies": { | ||
| "eslint": "^8.55.0", | ||
| "eslint-config-google": "^0.14.0", | ||
| "eslint-config-prettier": "^9.1.0", | ||
| "eslint-plugin-prettier": "^5.0.1", | ||
| "npm-watch": "^0.11.0", | ||
| "postcss": "^8.4.32", | ||
| "postcss-banner": "^4.0.1", | ||
| "prettier": "^3.1.1", | ||
| "rimraf": "^5.0.5", | ||
@@ -54,0 +56,0 @@ "rollup": "^4.7.0", |
241
README.md
@@ -11,5 +11,5 @@ <h1 align="center"> | ||
| [](https://www.npmjs.com/package/@placekit/autocomplete-js?activeTab=readme) | ||
| [](./LICENSE) | ||
| [](https://www.npmjs.com/package/@placekit/autocomplete-js?activeTab=readme) | ||
| [](./LICENSE) | ||
| </div> | ||
@@ -30,6 +30,9 @@ | ||
| If you already use a components library with an autocomplete field, or need a more advanced usage, please refer to our [PlaceKit JS client](https://github.com/placekit/client-js) reference and its [examples](https://github.com/placekit/client-js/tree/main/examples). | ||
| If you already use a components library with an autocomplete field, or need a more advanced usage, please refer to our [PlaceKit JS client](https://github.com/placekit/client-js) reference. | ||
| For React implementations, check our [PlaceKit Autocomplete React](https://github.com/placekit/autocomplete-react) library. And for Vue implementations, check our [Vue.js example](./examples/autocomplete-js-vue/). | ||
| Framework specific implementations: | ||
| - [PlaceKit Autocomplete React](https://github.com/placekit/autocomplete-react) - [Vue.js example](https://github.com/placekit/examples/tree/main/examples/autocomplete-js-vue/). | ||
| - [Svelte example](https://github.com/placekit/examples/tree/main/examples/autocomplete-js-svelte/). | ||
| ## ✨ Features | ||
@@ -51,4 +54,7 @@ | ||
| ```html | ||
| <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@placekit/autocomplete-js@2.1.5/dist/placekit-autocomplete.min.css" /> | ||
| <script src="https://cdn.jsdelivr.net/npm/@placekit/autocomplete-js@2.1.5"></script> | ||
| <link | ||
| rel="stylesheet" | ||
| href="https://cdn.jsdelivr.net/npm/@placekit/autocomplete-js@2.1.6/dist/placekit-autocomplete.min.css" | ||
| /> | ||
| <script src="https://cdn.jsdelivr.net/npm/@placekit/autocomplete-js@2.1.6"></script> | ||
| ``` | ||
@@ -61,3 +67,3 @@ | ||
| <script> | ||
| const pka = placekitAutocomplete('<your-api-key>', { | ||
| const pka = placekitAutocomplete('<your-public-api-key>', { | ||
| target: '#placekit', | ||
@@ -73,3 +79,3 @@ // other options... | ||
| <script type="module"> | ||
| import placekitAutocomplete from 'https://cdn.jsdelivr.net/npm/@placekit/autocomplete-js@2.1.5/dist/placekit-autocomplete.esm.js'; | ||
| import placekitAutocomplete from 'https://cdn.jsdelivr.net/npm/@placekit/autocomplete-js@2.1.6/dist/placekit-autocomplete.esm.js'; | ||
| const pka = placekitAutocomplete(/* ... */); | ||
@@ -99,3 +105,3 @@ // ... | ||
| const pka = placekitAutocomplete('<your-api-key>', { | ||
| const pka = placekitAutocomplete('<your-public-api-key>', { | ||
| target: '#placekit', | ||
@@ -109,3 +115,3 @@ // other options... | ||
| 👉 **Check out our [examples](./examples) for different use cases!** | ||
| 👉 **Check out our [examples](https://github.com/placekit/examples) for different use cases!** | ||
@@ -131,6 +137,6 @@ ## 🧰 Reference | ||
| PlaceKit Autocomplete initialization function returns a PlaceKit Autocomplete client, named `pka` in all examples. | ||
| PlaceKit Autocomplete initialization function returns a PlaceKit Autocomplete client, named `pka` in all snippets below. | ||
| ```js | ||
| const pka = placekitAutocomplete('<your-api-key>', { | ||
| const pka = placekitAutocomplete('<your-public-api-key>', { | ||
| target: '#placekit', | ||
@@ -142,5 +148,5 @@ countries: ['fr'], | ||
| | Parameter | Type | Description | | ||
| | --- | --- | --- | | ||
| | `apiKey` | `string` | API key | | ||
| | Parameter | Type | Description | | ||
| | --------- | ------------------------------ | ---------------------------------------------- | | ||
| | `apiKey` | `string` | API key | | ||
| | `options` | `key-value mapping` (optional) | Global parameters (see [options](#pkaoptions)) | | ||
@@ -166,14 +172,14 @@ | ||
| | Option | From | Type | Default | Description | | ||
| | --- | --- | --- | --- | --- | | ||
| | `target` | AutoComplete | `string\|Element` | `-` | Target input element or (unique) selector. | | ||
| | `panel` | AutoComplete | `object?` | `(...)` | Suggestions panel options, see [Panel options](#panel-options). | | ||
| | `format` | AutoComplete | `object?` | `(...)` | Formatting options, see [Format options](#format-options). | | ||
| | `countryAutoFill` | AutoComplete | `boolean?` | `true` | Automatically detect current country by IP and fill input when `types: ['country']`. | | ||
| | `countrySelect` | AutoComplete | `boolean?` | `true` | Show/hide country selector<sup>[(1)](#ft1)[(2)](#ft2)</sup>. | | ||
| | `maxResults` | JS client | `integer` | `5` | Number of results per page. | | ||
| | `language` | JS client | `string?` | `undefined` | Preferred language for the results<sup>[(3)](#ft3)</sup>, [two-letter ISO](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code. Supported languages are `en` and `fr`. By default the results are displayed in their 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` | JS client | `string[]?` | `undefined` | Restrict search in specific countries. Array of [two-letter ISO](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country codes<sup>[(3)](#ft3)</sup>. | | ||
| | `coordinates` | JS client | `string?` | `undefined` | Coordinates to search around. Automatically set when calling [`pka.requestGeolocation()`](#pkarequestgeolocation). | | ||
| | Option | From | Type | Default | Description | | ||
| | ----------------- | ------------ | ----------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `target` | AutoComplete | `string\|Element` | `-` | Target input element or (unique) selector. | | ||
| | `panel` | AutoComplete | `object?` | `(...)` | Suggestions panel options, see [Panel options](#panel-options). | | ||
| | `format` | AutoComplete | `object?` | `(...)` | Formatting options, see [Format options](#format-options). | | ||
| | `countryAutoFill` | AutoComplete | `boolean?` | `true` | Automatically detect current country by IP and fill input when `types: ['country']`. | | ||
| | `countrySelect` | AutoComplete | `boolean?` | `true` | Show/hide country selector<sup>[(1)](#ft1)[(2)](#ft2)</sup>. | | ||
| | `maxResults` | JS client | `integer` | `5` | Number of results per page. | | ||
| | `language` | JS client | `string?` | `undefined` | Preferred language for the results<sup>[(3)](#ft3)</sup>, [two-letter ISO](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code. Supported languages are `en` and `fr`. By default the results are displayed in their 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` | JS client | `string[]?` | `undefined` | Restrict search in specific countries. Array of [two-letter ISO](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country codes<sup>[(3)](#ft3)</sup>. | | ||
| | `coordinates` | JS client | `string?` | `undefined` | Coordinates to search around. Automatically set when calling [`pka.requestGeolocation()`](#pkarequestgeolocation). | | ||
@@ -187,8 +193,8 @@ - <a id="ft1"><b>[1]</b></a>: Ignored if `countries` option is set (Country selector is hidden). | ||
| | Option | Type | Default | Description | | ||
| | --- | --- | --- | --- | | ||
| | `className` | `string` | `undefined` | Additional panel CSS class(es). | | ||
| | `offset` | `integer` | `4` | Gap between input and panel in pixels. | | ||
| | `strategy` | `'absolute' \| 'fixed'` | `absolute` | [Popper positioning strategy](https://popper.js.org/docs/v2/constructors/#strategy) | | ||
| | `flip` | `boolean` | `false` | Flip position top when overflowing. | | ||
| | Option | Type | Default | Description | | ||
| | ----------- | ----------------------- | ----------- | ----------------------------------------------------------------------------------- | | ||
| | `className` | `string` | `undefined` | Additional panel CSS class(es). | | ||
| | `offset` | `integer` | `4` | Gap between input and panel in pixels. | | ||
| | `strategy` | `'absolute' \| 'fixed'` | `absolute` | [Popper positioning strategy](https://popper.js.org/docs/v2/constructors/#strategy) | | ||
| | `flip` | `boolean` | `false` | Flip position top when overflowing. | | ||
@@ -199,11 +205,11 @@ </details> | ||
| | Option | Type | Default | Description | | ||
| | --- | --- | --- | --- | | ||
| | `flag` | `(countrycode: string) => string` | [see placekit-autocomplete.js](./src/placekit-autocomplete.js#L56) | DOM for flags. | | ||
| | `icon` | `(name: string, label: string) => string` | [see placekit-autocomplete.js](./src/placekit-autocomplete.js#L57) | DOM for icons. | | ||
| | `sub` | `(item: object) => string` | [see placekit-autocomplete.js](./src/placekit-autocomplete.js#L58-L60) | Format suggestion secondary text | | ||
| | `noResults` | `(query: string) => string` | [see placekit-autocomplete.js](./src/placekit-autocomplete.js#L61) | Format "no results" text. | | ||
| | `value` | `(item: object) => string` | `item.name` | Format input value when user picks a suggestion. | | ||
| | `applySuggestion` | `string` | `"Apply suggestion"` | ARIA label for "insert" icon. | | ||
| | `cancel` | `string` | `"Cancel"` | Label for cancelling country selection mode. | | ||
| | Option | Type | Default | Description | | ||
| | ----------------- | ----------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------ | | ||
| | `flag` | `(countrycode: string) => string` | [see placekit-autocomplete.js](./src/placekit-autocomplete.js#L56) | DOM for flags. | | ||
| | `icon` | `(name: string, label: string) => string` | [see placekit-autocomplete.js](./src/placekit-autocomplete.js#L57) | DOM for icons. | | ||
| | `sub` | `(item: object) => string` | [see placekit-autocomplete.js](./src/placekit-autocomplete.js#L58-L60) | Format suggestion secondary text | | ||
| | `noResults` | `(query: string) => string` | [see placekit-autocomplete.js](./src/placekit-autocomplete.js#L61) | Format "no results" text. | | ||
| | `value` | `(item: object) => string` | `item.name` | Format input value when user picks a suggestion. | | ||
| | `applySuggestion` | `string` | `"Apply suggestion"` | ARIA label for "insert" icon. | | ||
| | `cancel` | `string` | `"Cancel"` | Label for cancelling country selection mode. | | ||
@@ -230,5 +236,5 @@ </details> | ||
| | Parameter | Type | Description | | ||
| | --- | --- | --- | | ||
| | `opts` | `key-value mapping` (optional) | Global parameters (see [options](#pkaoptions)) | | ||
| | Parameter | Type | Description | | ||
| | --------- | ------------------------------ | ---------------------------------------------- | | ||
| | `opts` | `key-value mapping` (optional) | Global parameters (see [options](#pkaoptions)) | | ||
@@ -300,5 +306,5 @@ ### `pka.state` | ||
| | Parameter | Type | Description | | ||
| | --- | --- | --- | | ||
| | `query` | `string` | Input value. | | ||
| | Parameter | Type | Description | | ||
| | --------- | ---------- | -------------------------- | | ||
| | `query` | `string` | Input value. | | ||
| | `results` | `object[]` | Results returned from API. | | ||
@@ -310,7 +316,7 @@ | ||
| | 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. | | ||
| | 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. | | ||
@@ -321,5 +327,5 @@ ##### `error` | ||
| | Parameter | Type | Description | | ||
| | --- | --- | --- | | ||
| | `error` | `object` | Error details. | | ||
| | Parameter | Type | Description | | ||
| | --------- | -------- | -------------- | | ||
| | `error` | `object` | Error details. | | ||
@@ -330,5 +336,5 @@ ##### `dirty` | ||
| | Parameter | Type | Description | | ||
| | --- | --- | --- | | ||
| | `dirty` | `boolean` | `true` after the user modifies the value. | | ||
| | Parameter | Type | Description | | ||
| | --------- | --------- | ----------------------------------------- | | ||
| | `dirty` | `boolean` | `true` after the user modifies the value. | | ||
@@ -339,5 +345,5 @@ ##### `empty` | ||
| | Parameter | Type | Description | | ||
| | --- | --- | --- | | ||
| | `empty` | `boolean` | `true` if input is empty. | | ||
| | Parameter | Type | Description | | ||
| | --------- | --------- | ------------------------- | | ||
| | `empty` | `boolean` | `true` if input is empty. | | ||
@@ -348,4 +354,4 @@ ##### `freeForm` | ||
| | Parameter | Type | Description | | ||
| | --- | --- | --- | | ||
| | Parameter | Type | Description | | ||
| | ---------- | --------- | ---------------------------------------------- | | ||
| | `freeForm` | `boolean` | `true` on user input, `false` on `pick` event. | | ||
@@ -357,7 +363,7 @@ | ||
| | Parameter | Type | Description | | ||
| | --- | --- | --- | | ||
| | `geolocation` | `boolean` | `true` if granted, `false` if denied. | | ||
| | `position` | [`GeolocationPosition \| undefined`](https://developer.mozilla.org/en-US/docs/Web/API/GeolocationPosition) | Passed when `geolocation` is `true`. | | ||
| | `error` | [`string \| undefined`](https://developer.mozilla.org/en-US/docs/Web/API/GeolocationPosition) | Geolocation request error message. | | ||
| | Parameter | Type | Description | | ||
| | ------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------- | | ||
| | `geolocation` | `boolean` | `true` if granted, `false` if denied. | | ||
| | `position` | [`GeolocationPosition \| undefined`](https://developer.mozilla.org/en-US/docs/Web/API/GeolocationPosition) | Passed when `geolocation` is `true`. | | ||
| | `error` | [`string \| undefined`](https://developer.mozilla.org/en-US/docs/Web/API/GeolocationPosition) | Geolocation request error message. | | ||
@@ -368,5 +374,5 @@ ##### `countryMode` | ||
| | Parameter | Type | Description | | ||
| | --- | --- | --- | | ||
| | `bool` | `boolean` | `true` if open, `false` if closed. | | ||
| | Parameter | Type | Description | | ||
| | --------- | --------- | ---------------------------------- | | ||
| | `bool` | `boolean` | `true` if open, `false` if closed. | | ||
@@ -377,5 +383,5 @@ ##### `state` | ||
| | Parameter | Type | Description | | ||
| | --- | --- | --- | | ||
| | `state` | `object` | The current input state. | | ||
| | Parameter | Type | Description | | ||
| | --------- | -------- | ------------------------ | | ||
| | `state` | `object` | The current input state. | | ||
@@ -386,5 +392,5 @@ ##### `countryChange` | ||
| | Parameter | Type | Description | | ||
| | --- | --- | --- | | ||
| | `item` | `object` | Country details returned from API. | | ||
| | Parameter | Type | Description | | ||
| | --------- | -------- | ---------------------------------- | | ||
| | `item` | `object` | Country details returned from API. | | ||
@@ -408,6 +414,6 @@ ### `pka.handlers` | ||
| | Parameter | Type | Description | | ||
| | --- | --- | --- | | ||
| | `opts` | `key-value mapping` (optional) | `navigator.geolocation.getCurrentPosition` [options](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/getCurrentPosition) | | ||
| | `cancelUpdate` | `boolean` (optional) | If `false` (default), suggestions list updates immediately based on device location. | | ||
| | Parameter | Type | Description | | ||
| | -------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `opts` | `key-value mapping` (optional) | `navigator.geolocation.getCurrentPosition` [options](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/getCurrentPosition) | | ||
| | `cancelUpdate` | `boolean` (optional) | If `false` (default), suggestions list updates immediately based on device location. | | ||
@@ -455,6 +461,6 @@ The location will be store in the `coordinates` global options, you can still manually override it. | ||
| | Parameter | Type | Description | | ||
| | --- | --- | --- | | ||
| | `value` | `string | null` (optional) | New input value, operation ignored if `undefined` or `null`. | | ||
| | `notify` | `boolean` (optional) | Pass `true` to dispatch `change` and `input` events and update state (default `false`). | | ||
| | Parameter | Type | Description | | ||
| | --------- | -------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | ||
| | `value` | `string | null` (optional) | New input value, operation ignored if `undefined` or `null`. | | ||
| | `notify` | `boolean` (optional) | Pass `true` to dispatch `change` and `input` events and update state (default `false`). | | ||
@@ -481,2 +487,19 @@ ```js | ||
| ### Dark mode | ||
| THe whole autocomplete automatically switches to dark mode if `<body>` has a `.dark` class or a `data-theme="dark"` attribute. | ||
| You can also activate the dark mode on-demand by wrapping the input with a `.dark` class or a `data-theme="dark"` attribute, like `<div class="pka-input dark">...</div>`. The suggestions panel is appended to the body directly and doesn't share any ancestor with the input field other than `<body>`, so to activate the dark mode on-demand, pass the `.dark` class to the panel options: | ||
| ```js | ||
| const pka = placekitAutocomplete('<your-public-api-key>', { | ||
| target: '#placekit', | ||
| panel: { | ||
| className: 'dark', | ||
| }, | ||
| }); | ||
| ``` | ||
| ### CSS Variables | ||
| Colors, border-radius, font and overall scale (in `rem`) and even icons are accessible over variables: | ||
@@ -495,27 +518,28 @@ | ||
| --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-font-family: system-ui, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif, | ||
| 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; | ||
| --pka-z-index: 9999; | ||
| --pka-icon-pin: url("..."); | ||
| --pka-icon-pin: url('...'); | ||
| --pka-icon-street: var(--pka-icon-pin); | ||
| --pka-icon-city: url("..."); | ||
| --pka-icon-airport: url("..."); | ||
| --pka-icon-bus: url("..."); | ||
| --pka-icon-train: url("..."); | ||
| --pka-icon-townhall: url("..."); | ||
| --pka-icon-tourism: url("..."); | ||
| --pka-icon-noresults: url("..."); | ||
| --pka-icon-clear: url("..."); | ||
| --pka-icon-city: url('...'); | ||
| --pka-icon-airport: url('...'); | ||
| --pka-icon-bus: url('...'); | ||
| --pka-icon-train: url('...'); | ||
| --pka-icon-townhall: url('...'); | ||
| --pka-icon-tourism: url('...'); | ||
| --pka-icon-noresults: url('...'); | ||
| --pka-icon-clear: url('...'); | ||
| --pka-icon-cancel: var(--pka-icon-clear); | ||
| --pka-icon-insert: url("..."); | ||
| --pka-icon-check: url("..."); | ||
| --pka-icon-switch: url("..."); | ||
| --pka-icon-geo-off: url("..."); | ||
| --pka-icon-geo-on: url("..."); | ||
| --pka-icon-loading: url("..."); | ||
| --pka-icon-insert: url('...'); | ||
| --pka-icon-check: url('...'); | ||
| --pka-icon-switch: url('...'); | ||
| --pka-icon-geo-off: url('...'); | ||
| --pka-icon-geo-on: url('...'); | ||
| --pka-icon-loading: url('...'); | ||
| } | ||
| /* dark mode overrides */ | ||
| body.dark, | ||
| body[data-theme="dark"] { | ||
| .dark, | ||
| [data-theme='dark'] { | ||
| --pka-color-accent: 55, 131, 249; | ||
@@ -529,7 +553,4 @@ } | ||
| A dark mode is available whenever you add `.dark` class or `data-theme="dark"` attribute to the `<body>` element. | ||
| ## ⚠️ Additional notes | ||
| ⚠️ **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](https://placekit.io/about#contact). | ||
| ## ⚠️ Additional notes | ||
| - Setting a non-empty `value` attribute on the `<input>` will automatically trigger a first search request when the user focuses the input. | ||
@@ -540,1 +561,3 @@ | ||
| PlaceKit Autocomplete JS Library is an open-sourced software licensed under the [MIT license](./LICENSE). | ||
| ⚠️ **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](https://placekit.io/about#contact). |
Sorry, the diff of this file is too big to display
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is too big to display
No alert changes
Improved metrics
- Total package byte prevSize
292393
2.91%- Lines of code
7185
2.69%- Number of lines in readme file
535
4.49%Worsened metrics
- Dev dependency count
15
15.38%No dependency changes