Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/hartwork/vue-tristate-checkbox
Vue.js component implementing a cycling tristate checkbox that supports form submission
https://github.com/hartwork/vue-tristate-checkbox
checkbox indeterminate javascript js tri-state tri-state-checkboxes tristate vue-components vuejs vuejs-components vuejs2
Last synced: 8 days ago
JSON representation
Vue.js component implementing a cycling tristate checkbox that supports form submission
- Host: GitHub
- URL: https://github.com/hartwork/vue-tristate-checkbox
- Owner: hartwork
- License: mit
- Created: 2020-05-01T23:29:06.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2020-05-06T12:25:22.000Z (over 4 years ago)
- Last Synced: 2024-05-19T00:03:22.679Z (6 months ago)
- Topics: checkbox, indeterminate, javascript, js, tri-state, tri-state-checkboxes, tristate, vue-components, vuejs, vuejs-components, vuejs2
- Language: HTML
- Size: 26.4 KB
- Stars: 5
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: COPYING
Awesome Lists containing this project
README
# Cycling Tristate Checkbox Vue.js Component
An animation says more than a thousand words:
Left: Chromium, Linux
Right: Firefox, Linux, GTK theme "[Adapta](https://github.com/adapta-project/adapta-gtk-theme)"
## Why this component?
Browsers do not support fully functional tristate checkboxes out of the box. In particular:
- JavaScript is needed to activate indeterminate state.
- Clicking an indeterminate checkbox never gets you back to indeterminate state, there is no cycling through all three states out of the box.
- Form submission only sends `"on"` (or the value from `value=".."`) but never `"indeterminate"`.
This Vue component offers a fully functional cycling tristate checkbox.
It was written by [Sebastian Pipping](https://blog.hartwork.org/)
and is licensed under the [MIT license](https://opensource.org/licenses/MIT).
I'm happy about [bugs reports](https://github.com/hartwork/vue-tristate-checkbox/issues) for any issues you find.
If you like this component please support it with a star ★. Thank you!
## Features
- An API that is very close to how you'd use regular binary checkboxes with Vue.js
- Support for form submission (using properties `name`, `value`, `value-indeterminate`)
- Cycles through all three states while clicking: off, on, intermediate, off, on,…
- Support for keyboard navigation using tabulator and spacebar
- Support for integration with ``, either
- bound using `for=".."` or
- surrounding the component as a parent node
- Uses checkbox rendering native to the browser
## Design decisions
- Use native checkboxes as rendered by the browser for a look native to the current environment
- Be as close to `` as possible, e.g. support attributes `checked`, `disabled`, `id`, `name`, `value` with the same naming
- Be as close to Vue's own take on checkboxes, e.g. support attributes `v-model`, `true-value`, `false-value` with the same naming
- Support a binary mode so the component _can_ take over all checkboxes in an app in a uniform way if desired
- (The component comes as a plain `.js` rather than a `.vue` file to keep things simple… but I'm open to arguments why a `.vue` file would greatly benefit this very case.)
# How to use
## With `v-model`
```html
var app = new Vue({
el: '#app',
data: {
tribool_ref: null // i.e. indeterminate state
}
})
```
For a more elaborate version of this very example, please see
[`demo_with_vmodel.htm`](https://github.com/hartwork/vue-tristate-checkbox/blob/master/demo_with_vmodel.htm).
## Without `v-model`
```html
var app = new Vue({el: '#app'})
```
Without `v-model` internal state storage is used.
In the example above, it can be accessed at `app.$refs.r1.state`.
For a more elaborate version of this very example, please see
[`demo_without_vmodel.htm`](https://github.com/hartwork/vue-tristate-checkbox/blob/master/demo_without_vmodel.htm).
# API
All properties documented below are **optional**.
## Model configuration
| Property | Type | Default value | Description |
|---|---|---:|---|
| v-model | String | n/a | External data property to use for storage of state |
| true-value | String/Boolean | true | Model value to use for checked state |
| false-value | String/Boolean | false | Model value to use for unchecked state |
| null-value | String/Boolean | null | Model value to use for indeterminate state |
## Form submission
| Property | Type | Default value | Description |
|---|---|---:|---|
| name | String | n/a | Name to use during form submission; set to enable form submission |
| value | String | "on" | Form submission value to use for checked state |
| value-indeterminate | String | "indeterminate" | Form submission value to use for indeterminate state |
## Behavior switches
These properties are mostly useful in absence of `v-model`.
| Property | Type | Default value | Description |
|---|---|---:|---|
| binary | Boolean | false | Whether to revert back to a binary checkbox, wins over indeterminate |
| checked | Boolean | false | Whether to start out checked |
| disabled | Boolean | false | Whether to start out disabled |
| indeterminate | Boolean | false | Whether to start out indeterminate, wins over checked |
## HTML anchor
Useful for URLs and binding a label with `for=".."`.
| Property | Type | Default value | Description |
|---|---|---:|---|
| id | String | n/a | HTML node ID to use for the checkbox node of the component |
# Contributing
Bug reports, feature requests, and pull requests are welcome, in general.
# License
**vue-tristate-checkbox** is licensed under
the [MIT license](https://opensource.org/licenses/MIT).
If you like this component please support it with a star ★. Thank you!