A tutorial for service.flatcheckbox.jquery - Styleable Checkbox

December 3, 2015

Overview

service.flatcheckbox.jquery is a small jQuery plugin that serves 2 purposes:

It styles a checkbox any way you want by hiding the <input type="checbox" /> element and replacing it with a styled <div>.
It binds a 'onChecked' and 'onUnChecked' event handler to the element.

Although the <input> selector element will be hidden the plugin updates the 'checked' attribute of the element to match the 'checked/unchecked' condition of the plugin. This means that correct state information will always be passed to the server when the <input> element is part of a submitted form.

Although with CSS3 it is possible to re-style the default checkbox without using javascript I am not a fan of that solution. The reason for this is that until now (end 2014) it isn't fully supported across all browsers and, more importantly, if you need javascript anyhow to hook up an event handler why would the CSS solution then be 'better' than the element replacement hack?

Demo

Click here for a demo.

Download

You can download the latest version of the plugin at GitHub.

Usage

To use the plugin start with adding the following in your header section:

<link rel="stylesheet" type="text/css" href="[your-path]/service.flatcheckbox.jquery.css" />
<script src="[your-path]/service.flatcheckbox.jquery.min.js"></script>

In your html, define the checkbox in the usual way through an <input type="checkbox" /> element.
Note: If you want to have a label element then don't specify that label here. You have the possibility to attach a label when assigning the checkbox to the plugin component.

<!-- A checkbox that initially is 'checked' -->
<input id="chkbox1" type="checkbox" checked />

<!-- A checkbox that initially is 'unchecked' -->
<input id="chkbox2" type="checkbox" />

Then, write some javascript to bind the checkbox element(s) to the plugin, hookup an event handler to process 'checked' and 'unchecked' events, and optionally attach a label to the checkbox.

<script type="text/javascript">

  // Execute on page load
  $(function () {

    // Initialize checkboxes
    // 1. First checkbox has a label
    $('#chkbox1').flatcheckbox({
      label: "Show past activities",
      onChecked: function (el) {
        // Handle event that the checkbox is 'checked'
        ...
      },
      onUnChecked: function (el) {
        // Handle event that the checkbox is 'unchecked'
        ...
      },
    });

    // 2. Second checkbox has no label
    $('#chkbox2').flatcheckbox({
      onChecked: function (el) {
        // Handle event that the checkbox is 'checked'
        ...
      },
      onUnChecked: function (el) {
        // Handle event that the checkbox is 'unchecked'
        ...
      },
    });

  });

</script>

The above is all what you need to have a fully stylable checkbox with the necessary event handlers to process the state changes that happen on the checkbox.

Different labels

The plugin also allows you to change the label text at any point in time; e.g. have different labels for state 'checked' and state 'unchecked'. Simply invoke the following method call:

 $('#chkbox1').flatcheckbox('label', 'Uncheck to disable processing');

Programmatically uncheck a checkbox (e.g. when another checkbox is checked)

For those who want this there is the possibility to uncheck a checkbox through javascript by invoking the 'uncheck' method of the plugin. You can use this for instance when you have a set of checkboxes and you want to have only 1 checkbox checked at a given time.

The way to accomplish this is to have a 'onChecked' handler for each checkbox and invoke the 'uncheck' method on each of the other checkboxes.

The following example explains this for 2 checkboxes.

 $('#chkbox5').flatcheckbox({
   onChecked: function (el) {
     $('#chkbox6').flatcheckbox('uncheck');
   },
   onUnChecked: function (el) {
     ...
   }
 });
 $('#chkbox6').flatcheckbox({
   onChecked: function (el) {
     $('#chkbox5').flatcheckbox('uncheck');
   },
   onUnChecked: function (el) {
     ...
   }
 });

Styling

As explained before, styling is done by hiding the checkbox (<input />) element and inserting the following div element behind the hidden one.

  <div class="flcheckbox">
      <span class="ckbBox"></span>
      <span class="ckbText">[label]</span>
  </div>

The first span allows you to style the checkbox. The css file that comes with the component creates a 'flat' checkbox (comparable with how you see checkboxes on Windows 8.x apps).
The second span allows you to style the optional label.

Note: when the checkbox is in state 'checked' the component adds class flchecked to the inserted div element.

API

Initialization method

[jqObject(s)].flatcheckbox(options)

The options argument is a javascript associative array (an object with key/value pairs) that allows you to initialize the plugin with some properties.

Properties

label

Type: String
Default: ""
This property is optional. If it is provided then the component will assign the string to the second span element of the inserted div. See the above section about styling.

onChecked

Type: callback function
Signature: onChecked: function (el) { }
el: The DOM element that was checked.
This callback is called when the user checks the checkbox.

onUnChecked

Type: callback function
Signature: onUnChecked: function (el) { }
el: The DOM element that was unchecked.
This callback is called when the user unchecks the checkbox.

Other methods

label

Signature: [jqObject(s)].flatcheckbox('label', 'labelText');
labelText: String - This parameter contains the text that must be assigned to the label element.
You can call this method to set/replace the text of the <span> element that is provided to show a label for the checkbox.

uncheck

Signature: [jqObject(s)].flatcheckbox('uncheck');
You can call this method to uncheck the checkbox.