{"id":13452160,"url":"https://github.com/github/auto-complete-element","last_synced_at":"2025-05-14T05:10:05.244Z","repository":{"id":37550254,"uuid":"129146927","full_name":"github/auto-complete-element","owner":"github","description":"Auto-complete input values from server search results.","archived":false,"fork":false,"pushed_at":"2025-04-14T20:46:01.000Z","size":1716,"stargazers_count":376,"open_issues_count":5,"forks_count":59,"subscribers_count":259,"default_branch":"main","last_synced_at":"2025-05-13T20:59:46.520Z","etag":null,"topics":["custom-elements","web-components"],"latest_commit_sha":null,"homepage":"https://github.github.com/auto-complete-element/examples/","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/github.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":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-04-11T19:56:58.000Z","updated_at":"2025-04-14T20:46:04.000Z","dependencies_parsed_at":"2024-02-20T20:47:43.954Z","dependency_job_id":"13e819ef-f5a4-4f86-9494-895ce58e3d79","html_url":"https://github.com/github/auto-complete-element","commit_stats":{"total_commits":247,"total_committers":18,"mean_commits":"13.722222222222221","dds":0.7530364372469636,"last_synced_commit":"93756e4e713e43cc5ec99d6b4894406009492fff"},"previous_names":[],"tags_count":43,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fauto-complete-element","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fauto-complete-element/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fauto-complete-element/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fauto-complete-element/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/github","download_url":"https://codeload.github.com/github/auto-complete-element/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254076850,"owners_count":22010611,"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":["custom-elements","web-components"],"created_at":"2024-07-31T07:01:15.286Z","updated_at":"2025-05-14T05:10:05.190Z","avatar_url":"https://github.com/github.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# \u0026lt;auto-complete\u0026gt; element\n\nAuto-complete input values from server search results.\n\n## Installation\n\n```\n$ npm install --save @github/auto-complete-element\n```\n\n## Usage\n\n### Script\n\nImport as ES modules:\n\n```js\nimport '@github/auto-complete-element'\n```\n\nWith a script tag:\n\n```html\n\u003cscript type=\"module\" src=\"./node_modules/@github/auto-complete-element/dist/bundle.js\"\u003e\n```\n\n### Markup\n\n```html\n\u003cauto-complete src=\"/users/search\" for=\"users-popup\"\u003e\n  \u003cinput type=\"text\" name=\"users\"\u003e\n  \u003c!--\n    Optional clear button:\n    - id must match the id of the input or the name of the input plus \"-clear\"\n    - recommended to be *before* UL elements to avoid conflicting with their blur logic\n\n    Please see Note below on this button for more details\n  --\u003e\n  \u003cbutton id=\"users-clear\"\u003eX\u003c/button\u003e\n  \u003cul id=\"users-popup\"\u003e\u003c/ul\u003e\n  \u003c!--\n    Optional div for screen reader feedback. Note the ID matches the ul, but with -feedback appended.\n    Recommended: Use a \"Screen Reader Only\" class to position the element off the visual boundary of the page.\n  --\u003e\n  \u003cdiv id=\"users-popup-feedback\" class=\"sr-only\"\u003e\u003c/div\u003e\n\u003c/auto-complete\u003e\n```\n\nIf you want to enable auto-select (pressing Enter in the input will select the first option), using the above example:\n```html\n\u003cauto-complete data-autoselect=\"true\" src=\"/users/search\" for=\"users-popup\"\u003e\n...\n\u003c/auto-complete\u003e\n```\n\nThe server response should include the items that matched the search query.\n\n```html\n\u003cli role=\"option\"\u003eHubot\u003c/li\u003e\n\u003cli role=\"option\"\u003eBender\u003c/li\u003e\n\u003cli role=\"option\"\u003eBB-8\u003c/li\u003e\n\u003cli role=\"option\" aria-disabled=\"true\"\u003eR2-D2 (powered down)\u003c/li\u003e\n```\n\nThe `data-autocomplete-value` attribute can be used to define the value for an\nitem whose display text needs to be different:\n\n```html\n\u003cli role=\"option\" data-autocomplete-value=\"bb8\"\u003eBB-8 (astromech)\u003c/li\u003e\n```\n\nUse `data-no-result-found=\"true\"` to show a no results message inside the autocomplete popover. Be sure to add `role=\"presentation\"` \nto this element so that screen readers do not mistake this as an auto-complete option. The auto-complete-element has built in functionality that\nhandles aria-live announcing number of search results so this should be purely decorative. \n\n```html\n\u003cli role=\"presentation\" aria-hidden=\"true\" data-no-result-found=\"true\"\u003eNo results found!\u003c/li\u003e\n```\n\n### A Note on Clear button\nWhile `input type=\"search\"` comes with an `x` that clears the content of the field and refocuses it on many browsers, the implementation for this control is not keyboard accessible, and so we've opted to enable a customizable clear button so that your keyboard users will be able to interact with it.\n\nAs an example:\n\u003e In Chrome, this 'x' isn't a button but a div with a pseudo=\"-webkit-search-cancel-button\". It doesn't have a tab index or a way to navigate to it without a mouse. Additionally, this control is only visible on mouse hover.\n\n\n## Attributes\n\n- `open` is true when the auto-complete result list is visible\n- `value` is the selected value from the list or the empty string when cleared\n\n## Properties\n\n- `fetchResult` you can override the default method used to query for results by overriding this property: `document.querySelector('auto-complete').fetchResult = async (url) =\u003e (await fetch(url)).text()`\n\n## Events\n\n### Network request lifecycle events\n\nRequest lifecycle events are dispatched on the `\u003cauto-complete\u003e` element. These events do not bubble.\n\n- `loadstart` - The server fetch has started.\n- `load` - The network request completed successfully.\n- `error` - The network request failed.\n- `loadend` - The network request has completed.\n\nNetwork events are useful for displaying progress states while the request is in-flight.\n\n```js\nconst completer = document.querySelector('auto-complete')\nconst container = completer.parentElement\ncompleter.addEventListener('loadstart', () =\u003e container.classList.add('is-loading'))\ncompleter.addEventListener('loadend', () =\u003e container.classList.remove('is-loading'))\ncompleter.addEventListener('load', () =\u003e container.classList.add('is-success'))\ncompleter.addEventListener('error', () =\u003e container.classList.add('is-error'))\n```\n\n### Auto-complete events\n\n**`auto-complete-change`** is dispatched after a value is selected. In `event` you can find:\n\n- `relatedTarget`: The HTMLInputElement controlling the auto-complete result list.\n\n```js\ncompleter.addEventListener('auto-complete-change', function(event) {\n  console.log('Auto-completed value chosen or cleared', completer.value)\n  console.log('Related input element', event.relatedTarget)\n})\n```\n\n### CSP Trusted Types\n\nYou can call\n`setCSPTrustedTypesPolicy(policy: TrustedTypePolicy | Promise\u003cTrustedTypePolicy\u003e | null)`\nfrom JavaScript to set a\n[CSP trusted types policy](https://web.dev/trusted-types/), which can perform\n(synchronous) filtering or rejection of the `fetch` response before it is\ninserted into the page:\n\n```ts\nimport AutoCompleteElement from 'auto-complete-element'\nimport DOMPurify from 'dompurify' // Using https://github.com/cure53/DOMPurify\n\n// This policy removes all HTML markup except links.\nconst policy = trustedTypes.createPolicy('links-only', {\n  createHTML: (htmlText: string) =\u003e {\n    return DOMPurify.sanitize(htmlText, {\n      ALLOWED_TAGS: ['a'],\n      ALLOWED_ATTR: ['href'],\n      RETURN_TRUSTED_TYPE: true\n    })\n  }\n})\nAutoCompleteElement.setCSPTrustedTypesPolicy(policy)\n```\n\nThe policy has access to the `fetch` response object. Due to platform\nconstraints, only synchronous information from the response (in addition to the\nHTML text body) can be used in the policy:\n\n```ts\nimport AutoCompleteElement from 'auto-complete-element'\n\nconst policy = trustedTypes.createPolicy('require-server-header', {\n  createHTML: (htmlText: string, response: Response) =\u003e {\n    if (response.headers.get('X-Server-Sanitized') !== 'sanitized=true') {\n      // Note: this will reject the contents, but the error may be caught before it shows in the JS console.\n      throw new Error('Rejecting HTML that was not marked by the server as sanitized.')\n    }\n    return htmlText\n  }\n})\nAutoCompleteElement.setCSPTrustedTypesPolicy(policy)\n```\n\nNote that:\n\n- Only a single policy can be set, shared by all `AutoCompleteElement` fetches.\n- You should call `setCSPTrustedTypesPolicy()` ahead of any other load of\n  `auto-complete` element in your code.\n  - If your policy itself requires asynchronous work to construct, you can also\n    pass a `Promise\u003cTrustedTypePolicy\u003e`.\n  - Pass `null` to remove the policy.\n- Not all browsers\n  [support the trusted types API in JavaScript](https://caniuse.com/mdn-api_trustedtypes).\n  You may want to use the\n  [recommended tinyfill](https://github.com/w3c/trusted-types#tinyfill) to\n  construct a policy without causing issues in other browsers.\n\n## Browser support\n\nBrowsers without native [custom element support][support] require a [polyfill][].\n\n- Chrome\n- Firefox\n- Safari\n- Microsoft Edge\n\n[support]: https://caniuse.com/#feat=custom-elementsv1\n[polyfill]: https://github.com/webcomponents/custom-elements\n\n## Development\n\n```\nnpm install\nnpm test\n```\n\nTo view changes locally, run `npm run examples`.\n\nIn `examples/index.html`, uncomment `\u003c!--\u003cscript type=\"module\" src=\"./dist/bundle.js\"\u003e\u003c/script\u003e--\u003e` and comment out the script referencing the `unpkg` version. This allows you to use the `src` code in this repo. Otherwise, you will be pulling the latest published code, which will not reflect the local changes you are making.\n\n## Accessibility Testing\n\nWe have included some custom rules that assist in providing guardrails to confirm this component is being used accessibly.\n\nIf you are using the `axe-core` library in your project,\n```js\nimport axe from 'axe-core'\nimport autoCompleteRulesBuilder from '@github/auto-complete-element/validator'\n\nconst autoCompleteRules = autoCompleteRulesBuilder() // optionally, pass in your app's custom rules object, it will build and return the full object\n\naxe.configure(autoCompleteRules)\naxe.run(document)\n```\n\n## Validate usage in your project\n\nTo confirm your usage is working as designed,\n```js\nimport {validate} from '@github/auto-complete-element/validator' \n\nvalidate(document)\n```\nPasses and failures may be determined by the length of the `passes` and `violations` arrays on the returned object:\n```js\n{\n  passes: [],\n  violations: []\n}\n```\n\n## License\n\nDistributed under the MIT license. See LICENSE for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithub%2Fauto-complete-element","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgithub%2Fauto-complete-element","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithub%2Fauto-complete-element/lists"}