vue-a11y-combobox
A Vue component that implements the WAI-ARIA authoring practices for a Combobox.
Preface
I am no regular screenreader user. I followed the authoring practices to the best of my understanding. If something seems off, please open an issue.
The current implementation only covers the List autocomplete with manual selection part of the authoring practices.
Installation
No rocket science here. Although rockets are cool, tbh. 🚀 Just install the component from npm.
npm install vue-a11y-combobox --save-dev
If you use Yarn:
yarn add -D vue-a11y-combobox
Once the component is installed you need to import wherever you want to use it.
import A11yCombobox from 'vue-a11y-combobox';
Don’t forget to add it to the registered components (been there, done that):
components: {
A11yCombobox,
// ... all the other amazing components
}
Demo
You can find a live demo on vue-a11y-combobox.code.ovl.design.
API
Props
-
items
: An array of items to be displayed. The items of the array must be objects that have atitle
andid
property. If an empty array is passed, the message set in thenoResultsMessage
prop is shown. Defaults to an empty array. -
inputLabel
: The label text of the input. Required. -
isStyled
: Whether or not default styles should be applied. Defaults to false. See section Styles below. -
noResultsMessage
: Text that should be shown if no results can be passed. Required.
Emitted events
-
input
: The component emits an input event if the value of the textbox changes. Please note that this is not debounced or throttled. -
foundResult
:keyup.enter
orclick
on an item emit the ID of the result.
Styles
The combobox exposes the following CSS classes for its parts:
Classname | Element |
---|---|
v-a11y-combobox | Root |
v-a11y-combobox__input | Text field |
v-a11y-combobox__list | List element |
v-a11y-combobox__list-item | List items |
By default no styles will be attached to these classes.
Setting the isStyled
prop to true
will enable some default styles. Those are scoped by adding the --is-styled
modifier to the respective element.
These styles add some little helpers (e.g. limiting the width, removing list styles, add position: absolute
to the list) and some minor styling.
You can adapt spacing and color of the component by accessing the following Custom Properties (supporting browsers):
Property | Default |
---|---|
--v-a11y-cb-space | 0.5rem |
--v-a11y-cb-clr-light | rgb(206, 206, 206) |
--v-a11y-cb-clr-dark | darkblue |
--v-a11y-cb-z-index | 10 |
Feedback & Contributions
Contributions are always welcome.
If you found a bug or want to request a feature, please open an issue.
If you wrote an enhancement or fixed a bug, open a Pull Request. Please follow the Fork & Pull Request workflow, as explained here.
Pull Requests should contain unit tests. However, if you are not sure how to write these tests, please do not hesitate to open a request. We can then figure out how to add necessary tests.
Thanks. 💞
Hack away
If you want to work with the code you can clone this repository and get started with these commands.
Install dependencies
yarn install // npm run install
Compiles and hot-reloads for development
yarn run serve
Compiles and minifies for production
yarn run build:bundle
This builds only the component. yarn run build
builds the file in the demo folder.
Lints and fixes files
yarn run lint
Run your unit tests
yarn run test:unit
yarn run test:unit --watch
will keep a server running that tests your changes as you save.
License
This project is licensed under the MIT license.
Author
Oscar Braunert | @ovlb | www.ovl.design