Checkbox checkbox.js

The checkbox control provides a customized look and feel that can be standardized across all browsers.

Usage

Via JavaScript

Initialize the checkbox control via JavaScript:

$('#myCheckbox').checkbox();

Via data-attributes

  • Checkbox input elements that exist when $.ready() executes that have data-initialize="checkbox" on their parent will be initialized immediately.
  • Checkbox input elements that are created with data-initialize="checkbox" after $.ready() executes will initialize when a mouseover event occurs on them.

Deprecated checkbox markup

Before v3.8.0, the checkbox control could be bound with $().checkbox(); or data-initialize="checkbox" to the div.checkbox or the input elements. This is no longer supported. Please update your markup and JavaScript to be bound to the label only.

Methods

Once your checkbox is initialized, you can execute any of the following methods on it:

.checkbox('check')
Ensures the checkbox is checked.
.checkbox('destroy')
Removes all functionality, jQuery data, and the markup from the DOM. Returns string of control markup as close to it's pre-initialization state as possible.
.checkbox('disable')
Ensures the checkbox is disabled.
.checkbox('enable')
Ensures the checkbox is enabled.
.checkbox('isChecked')
Returns true or false indicating the checked state of the checkbox.
.checkbox('toggle')
Toggles the checkbox between checked/unchecked states.
.checkbox('uncheck')
Ensures the checkbox is unchecked.

Events

Event Type Description
enabled.fu.checkbox Event fires when checkbox is enabled
disabled.fu.checkbox Event fires when checkbox is disabled
checked.fu.checkbox Event fires when checkbox is checked
unchecked.fu.checkbox Event fires when checkbox is unchecked

All checkbox events are fired on the .checkbox classed element. However, unlike the majority of Fuel UX controls, it is recommended to listen to and check the state of the checkbox control by listening to the native checkbox with the change event and check its status with the presence of the checked attribute. For the sample markup provided, this would be:


$('.checkbox input').on('change', function () {
  console.log( $(this).is(':checked') );
});

Examples

Default (stacked)


<div class="checkbox" id="myCheckbox">
  <label class="checkbox-custom" data-initialize="checkbox">
    <input class="sr-only" type="checkbox" value="">
    <span class="checkbox-label">Custom checkbox unchecked on page load</span>
  </label>
</div>
<div class="checkbox" id="myCheckbox2">
  <label class="checkbox-custom checked" data-initialize="checkbox">
    <input class="sr-only" checked="checked" type="checkbox" value="">
    <span class="checkbox-label">Custom checkbox checked on page load</span>
  </label>
</div>
<div class="checkbox" id="myCheckbox3">
  <label class="checkbox-custom disabled" data-initialize="checkbox">
    <input class="sr-only" disabled="disabled" type="checkbox" value="">
    <span class="checkbox-label">Disabled custom checkbox unchecked on page load</span>
  </label>
</div>
<div class="checkbox" id="myCheckbox4">
  <label class="checkbox-custom checked disabled" data-initialize="checkbox">
    <input class="sr-only" checked="checked" disabled="disabled" type="checkbox" value="">
    <span class="checkbox-label">Disabled custom checkbox checked on page load</span>
  </label>
</div>

Inline checkboxes

Use the .checkbox-inline class on checkboxes for controls that appear on the same line.


<label  class="checkbox-custom checkbox-inline" id="myCheckbox5" data-initialize="checkbox">
  <input class="sr-only" type="checkbox" value="option1"> <span class="checkbox-label">1</span>
</label>
<label  class="checkbox-custom checkbox-inline" id="myCheckbox6" data-initialize="checkbox">
  <input class="sr-only" checked="checked" type="checkbox" value="option2"> <span class="checkbox-label">2</span>
</label>
<label  class="checkbox-custom checkbox-inline disabled" id="myCheckbox7" data-initialize="checkbox">
  <input class="sr-only" disabled="disabled" type="checkbox" value="option3"> <span class="checkbox-label">3</span>
</label>

Addon checkboxes

Place any checkbox option within an input group's addon instead of text.


  <div class="input-group">
    <label class="input-group-addon checkbox-custom checkbox-inline" data-initialize="checkbox">
      <input class="sr-only" type="checkbox" value="option1">
    </label>
    <input class="form-control" type="text">
  </div>

Element toggling checkboxes

Use the data-toggle="{{selector}}" to automatically show or hide elements matching the selector within the body upon check or uncheck. This control works with any jQuery selector.

ID toggling container
Class toggling container
Class toggling container

<div class="checkbox" id="myCheckbox8">
  <label class="checkbox-custom" data-initialize="checkbox">
    <input class="sr-only" data-toggle="#checkboxToggleID" type="checkbox" value="option1">
    <span class="checkbox-label">Toggles element with matching ID</span>
  </label>
</div>
<label class="checkbox-custom checkbox-inline" id="myCheckbox9" data-initialize="checkbox">
  <input class="sr-only" data-toggle=".checkboxToggleCLASS" type="checkbox" value="option1">
  <span class="checkbox-label">Toggles elements with matching class.</span>
</label>

<div class="alert bg-info" id="checkboxToggleID">ID toggling container</div>
<div class="alert bg-success checkboxToggleCLASS">Class toggling container</div>
<div class="alert bg-success checkboxToggleCLASS">Class toggling container</div>

Highlighting checkboxes

Use the .highlight class to add a background highlight upon check. 


<div class="checkbox highlight" id="myCheckbox10">
  <label class="checkbox-custom highlight" data-initialize="checkbox">
    <input class="sr-only" type="checkbox" value="option1">
    This control highlights a block-level checkbox on check
  </label>
</div>
<label class="checkbox-custom checkbox-inline highlight" id="myCheckbox11" data-initialize="checkbox">
  <input class="sr-only" type="checkbox" value="option2">
  This control highlights an inline checkbox on check
</label>

Events

Unlike the majority of Fuel UX controls, it is recommended to listen to and check the state of the checkbox control by listening to the native checkbox with the change event and check its status with the presence of the checked attribute. For the sample markup provided, this would be:


$('.checkbox input').on('change', function () {
  console.log( $(this).is(':checked') );
});