Types
Checkbox
A standard checkbox
Radio
A checkbox can be formatted as a radio element. This means it is an exclusive option.
Slider
A checkbox can be formatted to emphasize the current selection state
Toggle
A checkbox can be formatted to show an on or off choice
States
Read-only
A checkbox can be read-only and unable to change states
Checked
A checkbox can be checked
Indeterminate
A checkbox can be indeterminate
Disabled
A checkbox can be read-only and unable to change states
Variations
Fitted
A fitted checkbox does not leave padding for a label
Examples
Using Callbacks
Checkbox has two versions of each state change behavior to let you determine whether the call should trigger checkbox callbacks.
Calling a behavior like check will trigger an elements callbacks, however using set checked will adjust the checkbox state without triggering callbacks
This differentiation is important to differentiate between programmatic changes, and user-invoked changes to state.
Example
Console
var
$console = $('.callback .console')
;
$('.callback.example .checkbox')
.checkbox()
.first().checkbox({
onChecked: function() {
$console.append('onChecked called
'); }, onUnchecked: function() { $console.append('onUnchecked called
'); }, onEnable: function() { $console.append('onEnable called
'); }, onDisable: function() { $console.append('onDisable called
'); }, onDeterminate: function() { $console.append('onDeterminate called
'); }, onIndeterminate: function() { $console.append('onIndeterminate called
'); }, onChange: function() { $console.append('onChange called
'); } }) ; // bind events to buttons $('.callback.example .button') .on('click', function() { $('.callback .checkbox').checkbox( $(this).data('method') ); }) ;
'); }, onUnchecked: function() { $console.append('onUnchecked called
'); }, onEnable: function() { $console.append('onEnable called
'); }, onDisable: function() { $console.append('onDisable called
'); }, onDeterminate: function() { $console.append('onDeterminate called
'); }, onIndeterminate: function() { $console.append('onIndeterminate called
'); }, onChange: function() { $console.append('onChange called
'); } }) ; // bind events to buttons $('.callback.example .button') .on('click', function() { $('.callback .checkbox').checkbox( $(this).data('method') ); }) ;
Grouped Checkboxes
The indeterminate state can be used to represent a value that is neither checked or unchecked.
This can be useful with groups where a "master" checkbox, should display the selections of several other checkboxes
$('.list .master.checkbox')
.checkbox({
// check all children
onChecked: function() {
var
$childCheckbox = $(this).closest('.checkbox').siblings('.list').find('.checkbox')
;
$childCheckbox.checkbox('check');
},
// uncheck all children
onUnchecked: function() {
var
$childCheckbox = $(this).closest('.checkbox').siblings('.list').find('.checkbox')
;
$childCheckbox.checkbox('uncheck');
}
})
;
$('.list .child.checkbox')
.checkbox({
// Fire on load to set parent value
fireOnInit : true,
// Change parent state on each child checkbox change
onChange : function() {
var
$listGroup = $(this).closest('.list'),
$parentCheckbox = $listGroup.closest('.item').children('.checkbox'),
$checkbox = $listGroup.find('.checkbox'),
allChecked = true,
allUnchecked = true
;
// check to see if all other siblings are checked or unchecked
$checkbox.each(function() {
if( $(this).checkbox('is checked') ) {
allUnchecked = false;
}
else {
allChecked = false;
}
});
// set parent checkbox state, but dont trigger its onChange callback
if(allChecked) {
$parentCheckbox.checkbox('set checked');
}
else if(allUnchecked) {
$parentCheckbox.checkbox('set unchecked');
}
else {
$parentCheckbox.checkbox('set indeterminate');
}
}
})
;
Checking Conditions
Checkboxes include four new callbacks beforeChecked, beforeUnchecked, beforeDeterminate, and beforeIndeterminate, returning false from these callbacks will cancel the action from occuring before the input value is updated.
$('.cancel.example .ui.checkbox')
.checkbox({
beforeChecked: function() {
var
luckyPerson = (Math.random() < 0.5)
;
return luckyPerson;
}
})
;
One-Way Choices
To make a user able to check a box, but unable to uncheck it, use the uncheckable setting.
To always disable a checkbox, add the property disabled to your input.
To make a checkbox read-only do not initialize it, or include the read-only class which will not allow events.
$('.state.example .checkbox')
.last()
.checkbox({
uncheckable: false
})
;
Attaching Events to other Elements
Checkbox can use the attach events behavior to attach events easily to other activating elements. This defaults to toggling, but other behaviors can be used as well.
$('.test.checkbox').checkbox('attach events', '.toggle.button');
$('.test.checkbox').checkbox('attach events', '.check.button', 'check');
$('.test.checkbox').checkbox('attach events', '.uncheck.button', 'uncheck');
Initializing
Checkbox
A checkbox does not require Javascript to function.
Full Featured Checkboxes
Using Javascript with checkboxes will automatically make the checkbox's label trigger a change in the input and provide callback functions. Additionally, some states like indeterminate can only be triggered with Javascript.
Linked Labels
If you just need labels to link without any other features of Javascript checkboxes, you can match the for attribute of the label to an input's id.
Behavior
Behaviors are accessible with Javascript using the syntax:
$('.ui.checkbox').checkbox(behavior, argumentOne, argumentTwo...);
| toggle | Switches a checkbox from current state |
| check | Set a checkbox state to checked |
| uncheck | Set a checkbox state to unchecked |
| indeterminate | Set as indeterminate checkbox |
| determinate | Set as determinate checkbox |
| enable | Enable interaction with a checkbox |
| set checked | Set a checkbox state to checked without callbacks |
| set unchecked | Set a checkbox state to unchecked without callbacks |
| set indeterminate | Set as indeterminate checkbox without callbacks |
| set determinate | Set as determinate checkbox without callbacks |
| set enabled | Enable interaction with a checkbox without callbacks |
| set disabled | Disable interaction with a checkbox without callbacks |
| attach events(selector, behavior) | Attach checkbox events to another element |
| is radio | Returns whether element is radio selection |
| is checked | Returns whether element is currently checked |
| is unchecked | Returns whether element is not checked |
| can change | Returns whether element is able to be changed |
| should allow check | Returns whether element can be checked (checking if already checked or `beforeChecked` would cancel) |
| should allow uncheck | Returns whether element can be unchecked (checking if already unchecked or `beforeUnchecked` would cancel) |
| should allow determinate | Returns whether element can be determinate (checking if already determinate or `beforeDeterminate` would cancel) |
| should allow indeterminate | Returns whether element can be indeterminate (checking if already indeterminate or `beforeIndeterminate` would cancel) |
| can uncheck | Returns whether element is able to be unchecked |
Checkbox
These settings are specific to checkbox, and determine the parameters of its behavior
| Default | Description | |
|---|---|---|
| uncheckable | auto | Setting to true/false will determine whether an input will allow no selection. Auto will set disallow this behavior only for radio boxes |
| fireOnInit | false | Whether callbacks for checked status should be fired on init as well as change |
| Context | Description | |
|---|---|---|
| onChange | HTML input element | Callback after a checkbox is either checked or unchecked. |
| onChecked | HTML input element | Callback after a checkbox is checked. |
| onIndeterminate | HTML input element | Callback after a checkbox is set to undeterminate. |
| onDeterminate | HTML input element | Callback after a checkbox is set to determinate. |
| onUnchecked | HTML input element | Callback after a checkbox is unchecked. |
| beforeChecked | HTML input element | Callback before a checkbox is checked. Can cancel change by returning false |
| beforeIndeterminate | HTML input element | Callback before a checkbox is set to undeterminate. Can cancel change by returning false |
| beforeDeterminate | HTML input element | Callback before a checkbox is set to determinate. Can cancel change by returning false |
| beforeUnchecked | HTML input element | Callback before a checkbox is unchecked. Can cancel change by returning false |
| onEnable | HTML input element | Callback after a checkbox is enabled. |
| onDisable | HTML input element | Callback after a checkbox is disabled. |
Module
These settings are native to all modules, and define how the component ties content to DOM attributes, and debugging settings for the module.
| Default | Description | |
|---|---|---|
| name | Checkbox | Name used in log statements |
| namespace | checkbox | Event namespace. Makes sure module teardown does not effect other events attached to an element. |
| selector |
selector : {
input : 'input[type=checkbox], input[type=radio]',
label : 'label'
}
|
Selectors used to find parts of a module |
| className |
className : {
checked : 'checked',
disabled : 'disabled',
radio : 'radio',
readOnly : 'read-only'
}
|
Class names used to determine element state |
| silent | False | Silences all console output including error messages, regardless of other debug settings. |
| debug | false | Debug output to console |
| performance | true | Show console.table output with performance metrics |
| verbose | false | Debug output includes all internal behaviors |
| errors |
error : {
method : 'The method you called is not defined.'
}
|
|