{"id":26481476,"url":"https://github.com/geocodeearth/autocomplete-element","last_synced_at":"2025-03-20T03:20:47.159Z","repository":{"id":39994055,"uuid":"357628174","full_name":"geocodeearth/autocomplete-element","owner":"geocodeearth","description":"A custom element for use with the Geocode Earth Autocomplete API.","archived":false,"fork":false,"pushed_at":"2024-03-12T18:01:37.000Z","size":138,"stargazers_count":8,"open_issues_count":5,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-16T04:27:35.644Z","etag":null,"topics":["autocomplete","autocomplete-component","geocoding","webcomponent"],"latest_commit_sha":null,"homepage":"https://geocode.earth","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/geocodeearth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-04-13T16:58:30.000Z","updated_at":"2023-12-01T07:34:49.000Z","dependencies_parsed_at":"2024-11-16T21:15:19.468Z","dependency_job_id":null,"html_url":"https://github.com/geocodeearth/autocomplete-element","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geocodeearth%2Fautocomplete-element","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geocodeearth%2Fautocomplete-element/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geocodeearth%2Fautocomplete-element/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geocodeearth%2Fautocomplete-element/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/geocodeearth","download_url":"https://codeload.github.com/geocodeearth/autocomplete-element/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244542202,"owners_count":20469289,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["autocomplete","autocomplete-component","geocoding","webcomponent"],"created_at":"2025-03-20T03:20:46.624Z","updated_at":"2025-03-20T03:20:47.154Z","avatar_url":"https://github.com/geocodeearth.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Geocode Earth Autocomplete Element\n\nAn autocomplete element (Web Component) for use with the [Geocode Earth](https://geocode.earth/) Autocomplete API.\n\n## Installation\n\n```bash\n$ npm install @geocodeearth/autocomplete-element\n```\n\nThe package is also available via GitHub Packages.\n\nThen import it:\n\n```js\nimport '@geocodeearth/autocomplete-element'\n```\n\nYou can also use a script tag referencing it locally:\n\n```html\n\u003cscript type=\"module\" src=\"./node_modules/@geocodeearth/autocomplete-element/dist/bundle.js\"\u003e\u003c/script\u003e\n```\n\n## Basic Usage\n\nOnce installed you can use the custom element:\n\n```html\n\u003cge-autocomplete api_key='ge-YOURKEY'\u003e\u003c/ge-autocomplete\u003e\n```\n\n## Attributes\n\nAll configuration happens through **attributes** on the element. `api_key` is the only required one (as without it you can’t access the API). All other available attributes are documented below.\n\n### `api_key`\n\u003e **required**, no default\n\nYour Geocode Earth API key. [Sign up for a free trial »](https://geocode.earth)\n\n### `throttle`\n\u003e defaults to `200`\n\nUsed to prevent firing a request for every keystroke as the user types, in milliseconds.\nThis is passed directly to the [`_.throttle`](https://lodash.com/docs/4.17.15#throttle) function.\n\n### `size`\n\u003e defaults to `10`\n\nControls how many results should be shown.\n\n### `placeholder`\n\u003e defaults to `Search a city or address`\n\nSets the placeholder text for the input field.\n\n### `autofocus`\n\u003e defaults to `false`\n\nSets whether the input should be automatically focused, can be set without an explicit value as it’s a boolean:\n\n```html\n\u003cge-autocomplete api_key=\"…\" autofocus\u003e\u003c/ge-autocomplete\u003e\n```\n\n### `lang`\n\u003e defaults to `Accept-Language` header, falls back to `en`\n\nSets the language in which results are returned.\n\n### `layers`\n\u003e defaults to all layers\n\nThe Geocode Earth dataset is a combination of multiple data layers. This attribute can be used to limit results to a specific layer (or multiple ones, comma separated). Please see our API documentation for a list of available layers: [geocode.earth/docs/reference/data_layers/](https://geocode.earth/docs/reference/data_layers/)\n\n### `focus.point.lat` \u0026 `focus.point.lon`\n\u003e defaults to unfocused\n\nSets latitude and longitude around which to focus results. In addition to providing results that are more relevant due to their proximity, setting a focus point is generally significantly faster than an unfocused query.\n\n### `boundary.country`\n\u003e defaults to unset (all countries)\n\nSets a country filter to only return results in the specified country. Use a comma separated list of [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country codes (2 or 3 letter variants).\n\n### `boundary.gid`\n\u003e defaults to unset (all GIDs)\n\nFilters results by parent ID, which can be used to search in areas smaller than a country and/or areas with shapes not well represented by rectangular bounding boxes.\n\n[Please see our documentation how to use this.](https://geocode.earth/docs/forward/customization/#restrict-results-by-parent-id)\n\n### `boundary.circle.lat`, `boundary.circle.lon`, `boundary.circle.radius`\n\u003e defaults to unset\n\nSearches within a circular region. Useful to return results in a radius around a known point. Note: all three parameters need to be set. The `radius` is defined in kilometers.\n\n### `boundary.rect.min_lat`, `boundary.rect.max_lon`, `boundary.rect.max_lat`, `boundary.rect.min_lon`\n\u003e defaults to unset\n\nSearches within a rectangular region. Same as with a circular boundary all 4 parameters have to be set.\n\nTip: You can look up a bounding box for a known region using [geojson.io](https://geojson.io/).\n\n## Events\n\nThe element also emits **events** as a user interacts with it. This is how you can be notified when a user selects a result, for example. The `event.detail` payload contains details about the event.\n\n**Note:** These events do not bubble, which means listeners have to be attached to the element directly (see examples below).\n\n|Event\u0026nbsp;Name|`event.detail`|Description|\n|---------------|--------------|-----------|\n|`select`       |`Feature`     |Dispatched when a user selects a suggested item from the list.|\n|`change`       |`string`      |Dispatched with every keystroke as the user types (not debounced).|\n|`features`       |`[]Feature`      |Dispatched when the GeoJSON features backing the UI change.|\n|`error`        |`Error`       |Dispatched if an error occures during the request (for example if the rate limit was exceeded.)|\n\n\n\n## Customization\n\nWe did our best to design the element in such a way that it can be used as is in a lot of different contexts without needing to adjust how it looks. However, there certainly can be situations where customization is necessary. The element supports three different customization APIs:\n\n1. Custom CSS (variables)\n2. A string template as well as\n3. A row template\n\n### 1. Custom CSS\n\nWe use CSS variables for almost all properties that you would want to customize. This includes the font family, background or shadow of the input and the hover state for a result just to name a few. For a list of all available variables please check the source CSS file directly ([`/src/autocomplete/autocomplete.css`](src/autocomplete/autocomplete.css)).\n\nYou can adjust these variables by placing a `\u003cstyle\u003e` tag _inside_ the element, like so:\n\n```html\n\u003cge-autocomplete api_key=\"…\"\u003e\n  \u003cstyle\u003e\n     :host {\n       --input-bg: salmon;\n       --input-color: green;\n       --loading-color: hotpink;\n    }\n  \u003c/style\u003e\n\u003c/ge-autocomplete\u003e\n```\n\n**Important:** While it is technically possible to override the actual classnames the element uses internally, we do not consider those part of the public API. That means they can change without a new major version, which could break your customization. The CSS variables on the other hand are specifically meant to be customized, which is why they will stay consistent even if the internal markup changes.\n\nIf you would like to customize a property for which there is no variable we’d be happy to accept a pull-request or issue about it.\n\n### 2. String Template\n\nIf you want to customize how a feature is turned into a string for rendering (in the results as well as the input field after it was selected), you can define a custom string template. This allows you to use the [lodash template language][_template] to access every property of the feature to build a custom string.\n\n```html\n\u003cge-autocomplete api_key=\"…\"\u003e\n  \u003ctemplate string\u003e\n    ${item.feature.properties.name} (${item.feature.properties.id}, ${item.feature.properties.source})\n  \u003c/template\u003e\n\u003c/ge-autocomplete\u003e\n```\n\n**Important:** Make sure to return a plain string here, no HTML. The reason for this is that this template will also be used in the input field itself after a result has been selected, which doesn’t support HTML.\n\n### 3. Row Template\n\nSimilar to the string template mentioned above, you can use the row template to define how a single row in the results is rendered. The key here is that this supports full HTML:\n\n```html\n\u003cge-autocomplete api_key=\"…\"\u003e\n  \u003ctemplate row\u003e\n    \u003cdiv class=\"custom-row ${item.active ? 'custom-row--active' : null}\"\u003e\n      \u003cimg src=\"/flags/${item.feature.properties.country_a.png}\" alt=\"${item.feature.properties.country_a}\"\u003e\n      \u003cspan\u003e${item.feature.properties.label}\u003c/span\u003e\n    \u003c/div\u003e\n  \u003c/template\u003e\n\u003c/ge-autocomplete\u003e\n```\n\n**Pro Tip™:** Use the `item.active` property to check if the current row is being hovered over or activated via arrow keys. See below for additional properties.\n\nThe example above could render a little flag icon for the result’s country, for example. You can customize the styling by defining custom classes in the same way you would customize the CSS variables. It’s best to prefix your classes to avoid conflicts with internal classnames of the element.\n\nThe [lodash template language][_template] supports much more than just straight variables. Please refer to their docs directly to understand how it works. It’s pretty powerful.\n\n  [_template]: https://lodash.com/docs/4.17.15#template\n\n\n### Additional Template Properties\n\nInside a template you can access the following properties:\n\n|Property|Type|Contains|\n|--------|----|--------|\n|`item.feature`|Object|The selected item, a [GeoJSON Feature][geojsonfeature]|\n|`item.active`|Boolean|Whether or not the current item is active (hovered or selected with arrow keys)|\n|`item.searchTerm`|String|The current value of the search input field|\n|`item.index`|Number|The index of the item in the result list|\n\n  [geojsonfeature]: https://github.com/geocodeearth/core-js/blob/main/src/geojson.ts\n\n## Example\n\nPlease see the `example` folder. You can follow the steps in the [**Development**](#development) section to run them directly, too.\n\n## Development\n\n```bash\n$ npm install\n$ npm run dev\n```\n\n## License\n\nThis code is licensed under the MIT license. Please see the `LICENSE` file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeocodeearth%2Fautocomplete-element","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeocodeearth%2Fautocomplete-element","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeocodeearth%2Fautocomplete-element/lists"}