{"id":18948993,"url":"https://github.com/junjizhi/accessible-combobox","last_synced_at":"2025-04-15T23:31:05.968Z","repository":{"id":57172401,"uuid":"305007822","full_name":"junjizhi/accessible-combobox","owner":"junjizhi","description":"Accessible Combobox (WAI-ARIA v1.2 compliant)","archived":false,"fork":false,"pushed_at":"2020-10-19T01:06:54.000Z","size":15,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-07T09:48:02.333Z","etag":null,"topics":["accessibility","accessible-components","aria","autocomplete","combobox"],"latest_commit_sha":null,"homepage":"","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/junjizhi.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}},"created_at":"2020-10-18T02:32:38.000Z","updated_at":"2024-02-27T03:51:19.000Z","dependencies_parsed_at":"2022-08-24T14:40:57.283Z","dependency_job_id":null,"html_url":"https://github.com/junjizhi/accessible-combobox","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junjizhi%2Faccessible-combobox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junjizhi%2Faccessible-combobox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junjizhi%2Faccessible-combobox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junjizhi%2Faccessible-combobox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/junjizhi","download_url":"https://codeload.github.com/junjizhi/accessible-combobox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223688650,"owners_count":17186299,"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":["accessibility","accessible-components","aria","autocomplete","combobox"],"created_at":"2024-11-08T13:15:23.322Z","updated_at":"2024-11-08T13:15:24.151Z","avatar_url":"https://github.com/junjizhi.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Accessible Combobox (WAI-ARIA v1.2)\n\n[![npm version](https://badge.fury.io/js/accessible-combobox.svg)](https://badge.fury.io/js/accessible-combobox)\n\nThis repo implements a WAI-ARIA v1.2 compliant combobox with a listbox and a dropdown button.\n\nFor more details, please check out my blog: [Building an Accessible Combobox](https://blog.junjizhi.com/all/technical/2020/10/18/a11y-combobox.html)\n\n## Demo\n\n![accessible combobox demo gif](https://user-images.githubusercontent.com/2715151/96359280-03a79d80-10df-11eb-909b-be8eed0ee6b8.gif)\n\n\n## Why ARIA v1.2, not v1.1?\n\nQuote from [the ARIA site](https://www.w3.org/TR/wai-aria-1.2/#combobox):\n\n\u003e The Guidance for combobox has changed significantly in ARIA 1.2 due to problems with implementation of the previous patterns. Authors and developers of User Agents, Assistive Technologies, and Conformance Checkers are advised to review this section carefully to understand the changes.\n\n[ARIA Wiki](https://github.com/w3c/aria/wiki/Resolving-ARIA-1.1-Combobox-Issues) also has detailed explanations of the version issues.\n\n__Essentially, if a combobox implementation follows ARIA v1.1 specs, it would have poor\nscreen reader support__.\n\nThe major differences between v1.1 and v1.2 include:\n- `role=\"combobox\"` is on a wrapper `\u003cdiv\u003e`(v.1.1) or `\u003cinput\u003e`(v.1.2)\n- `aria-owns` (v.1.1) vs. `aria-controls` (v1.2)\n\nAs a result, it is important to get these details right to make your combobox accessible.\n\n## Installation\n\n```bash\nnpm i accessible-combobox\n```\n\n## Usage\n\nHTML:\n\n```html\n\u003cinput id=\"cb1-input\"\n    type=\"text\"\n    role=\"combobox\"\n    aria-label=\"Enter a state\"\n    aria-autocomplete=\"both\"\n    aria-expanded=\"false\"\n    aria-controls=\"lb1\"\n    aria-haspopup=\"listbox\"\n    /\u003e\n\u003cbutton type=\"button\"\n      id=\"cb1-button\"\n      aria-label=\"open state list\"\n      tabindex=\"-1\"\u003e ▼\n\u003c/button\u003e\n\n\u003cul id=\"lb1\"\n    role=\"listbox\"\n    aria-label=\"States\"\u003e\n\u003c/ul\u003e\n\n\u003c!-- Hidden options list --\u003e\n\u003cul id=\"listbox-options\" class=\"hidden\"\u003e\n  \u003cli id=\"lb1-al\" class=\"hidden\"\u003e\n    Alabama\n  \u003c/li\u003e\n  \u003cli id=\"lb1-ak\" class=\"hidden\"\u003e\n    Alaska\n  \u003c/li\u003e\n  \u003c!-- ... --\u003e\n\u003c/ul\u003e\n```\n\nNotes:\n\n- You can wrap the input and the button in a div like in `example.js` if you want to put them in the same CSS class.\n- The two `ul` don't have to be placed next to the input or button. You can place them anywhere in the HTML.\n\nJavascript:\n\n```javascript\nnew Combobox(\n  document.getElementById(\"cb1-input\"),\n  document.getElementById(\"cb1-button\"),\n  document.getElementById(\"lb1\"),\n  \"Alabama\",\n  Array.from(document.querySelectorAll(\"#listbox-options \u003e li\")),\n  function () {\n    console.log(\"Showing items\");\n  },\n  function () {\n    console.log(\"Hiding items\");\n  },\n  function () {\n    console.log(\"Changing an item\");\n  },\n  function () {\n    console.log(\"An Error happens\");\n  }\n);\n```\n\nFor more details, check out `index.html` and `example.js`.\n\n## Explanations\nWhen workinng the ARIA v1.1 combobox, I found a few problems with [their reference implementation](https://www.w3.org/TR/wai-aria-practices/examples/combobox/aria1.1pattern/listbox-combo.html).\nThis repo is an improved version of accessible combobox implementation with ARIA v1.2 compliance.\n\nIn particular, I added a few properties to the Combobox class:\n  - Initial value\n  - More callback hooks to make it to extend and implement other behaviors\n  - ES6 class syntax\n\nFor more details, please check out [my blog](https://blog.junjizhi.com/all/technical/2020/10/18/a11y-combobox.html).\n\n### HTMl elements structure assumptions\n\nThe class requires the `input`, `button` and `ul` elements to have the correct `aria-*` attributes.\n\nTODO:\n\n- [ ] handle all ARIA related attributes in Javascript (in the Combobox constructor function).\n\n\n### Client side search\n\nSearch happens totally in the client side / browser. When user enters a search term, the script\nmatches the results with the term and renders the list. I do it this way because __[ARIA v1.2 specs](https://www.w3.org/TR/wai-aria-practices-1.2/#combobox)\nrequire updating `aria-selected` attributes of the options, and pointing `aria-activedescendent` to the selected option__. Because\nthese things are tightly coupled, using Javascript to rebuild the popup HTML with total control makes more sense to me, instead of assuming any HTML attributes.\n\nThe search requires a hidden list of available\noptions rendered in the HTML. In practice, the options list likely comes from the server side. It also makes it easy to work with existing framework (e.g., Rails or Phoenix) where the views are\nusually server side rendered.\n\n## Other libraries\n\nIf you are looking an accessible combobox in React, check out [Reach UI Combobox](https://reach.tech/combobox/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjunjizhi%2Faccessible-combobox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjunjizhi%2Faccessible-combobox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjunjizhi%2Faccessible-combobox/lists"}