aria-checkbox
v0.0.2
Published
Accessible, responsive, themeable, small footprint checkbox, supports tri-state, too
Downloads
2
Maintainers
schrotieReadme
aria-checkbox
Accessible, responsive, themeable, small footprint checkbox, supports tri-state, too
<aria-checkbox> is a themable checkbox web-component/custom-element. Simply load the script, e.g. in your document's <head> and add checkboxes to your document.
Okay, it's probably not that simple. AriaCheckbox is a class that handles the ARIA (i.e. accessibility) aspect of checkboxes. <aria-checkbox> comes with a couple of themes:
- classic
looks basically like a classical checkbox, just themed and with some gradients - material
is a material design checkbox variant - toggle
is a material design toggle button
Each comes with a simple theming interface. If you can decide to just use one kind and are happy with the look and feel just include the respective file, add you colors and enjoy:
aria-checkboxClassic.mjsaria-checkboxMaterial.mjsaria-checkboxToggle.mjs
What File to Load
You only need to load one file. Which one that is depends on your specific needs. As noted above, <aria-checkbox> comes with three pre-built themes. Thus first you should decide which theme to choose or if you want to build your own customized variant.
The pre-built dist (distribution) files are in the NPM package but not in the GitHub sources. If you loaded the latter you need to do npm i; npm run build to get them.
If you build your own, you should import AriaCheckbox from '.../src/aria-checkbox.mjs' and do your own build. If you build a web application with static source code (as opposed to a page that is dynamically assembled by server side rendering) you should import the source version of your chosen themed checkbox and have a custom build for your app.
If you want to use a pre-build checkbox decide which and next decide which build to load. Each theme comes with three builds. <aria-checkbox> uses the ShadowQuery micro library to simplify web component implementation. Two builds bundle it, one doesn't. If you use more stuff that also needs ShadowQuery use the version where it's not bundled. That way you don't have to load it multiple times.
- *.min.mjs minified EcmaScript Module without ShadowQuery
- *.min.js minified ES6 script file with ShadowQuery bundled - use for all modern browsers except Edge
- *.IE.min.js babel-transpiled ES5 for IE (and possibly Edge?) with ShadowQuery bundled
File sizes (gzipped): the minified boxes without ShadowQuery are ~2K, with ShadowQuery ~4K and transpiled with ShadowQuery ~13K.
Deployment & Polyfills
Older versions of current browsers and IE don't fully support web components and may miss modern language features. For the former you need to load a polyfill, for the latter you need to load the transpiled <aria-checkbox>.
In addition I strongly recommend that you load the polyfills only where required and don't load transpiled code for browsers that don't need it! Transpiled means that the code went through babel. The code is twice as big and slower than the native ES6 ... and simply won't work in at least some modern browsers.
Theming & Customization
The aria-checkbox visuals have no actual DOM, it's all CSS. Thus it is fully themeable, you can do whatever you like and still rely on aria-checkbox to handle accessibility and more (it sync the checkox's checked property, checked attribute and aria-checked attribute and can control other aria-checkboxes). Checkout the demo!
If you want to customize the look and feel I recommend implementing you own by extending AriaCheckbox and adding your own style. aria-checkbox.mjs exports a function defineAriaCheckbox(css, element). Call it and pass your CSS as the first argument. It will be put inside the custom-element's shadowDOM <style></style>. Optionally you can pass a tag-name as the second argument (defaults to aria-checkbox).
You may want to check out how the classic, material and toggle checkboxes do that, it's quite simple. You can either start from one of the themes that ship with <aria-checkbox> or start from scratch. You may still want to have a look at the shipped themes to figure out what selectors to use for your CSS. Thus you can easily create you own <my-checkbox> that looks exactly as you need.
Note that you have up to five DOM elements to play with in your theme:
- the
<aria-checkbox>element itself, selected with:hostin your CSS :host::beforevirtual CSS only element in the light DOM:host::afteras above:host slot::beforevirtual CSS only element in shadow DOM:host slot::afteras above
Note on IE
If you decide to build you own custom variant of <aria-checkbox> and you need to support IE, be aware that you need to persuade the ShadyCSS polyfill to actually style your checkbox. It's "just" a little code and if you use defineAriaCheckbox(css, element) the function will handle that for you. But if you inherit from AriaCheckbox manually, check the implementation of defineAriaCheckbox(css, element) to see what you need to do.
API
Attributes
- role="checkbox"
accessibility feature, set automatically - tabindex="0"
accessibility feature, set automatically - aria-checked
accessibility feature, can become "true", "false", or "mixed" - checked
for native checkbox compatibility - aria-controls
If you want one checkbox to control others, pass the controlled checkboxes's IDs to the controlling checkbox'saria-controlsattribute.
property
- checked
aria-checkedandcheckedattributes andcheckedproperty are always kept in sync. If you change any, the other will follow. Usearia-checkedfor styling. Foraria-checked="mixed"checkedattribute will be absent and property will befalse.
events
When the checkox's value changes due to the user's mouse or keyboard interaction, <aria-checkbox> will emit two event:
- change
- input
CSS custom properties
These are specific to the theme you use for the box. The shipped themes support the following:
- --aria-checkbox-bg-unchecked default: #a8a8a8
background color of unchecked box - --aria-checkbox-bg-checked default: #4787ef
background color of checked box - --aria-checkbox-fg-checked default: #fff
foreground color of checked box (i.e. checkmark color, not used by toggle)
This is what native checkboxes do. The original user event will be in event.detail.
Method
- toggle ... guess :-)
Accessibility features
See W3C example.