Checkboxradio Widget

Categories: Widgets

Checkboxradio Widgetversion added: 1.0

Description: Creates a checkboxradio widget

QuickNavExamples

Options

Methods

Events

Checkboxes

Checkboxes are used to provide a list of options where more than one can be selected. Traditional desktop checkboxes are not optimized for touch input so in jQuery Mobile, we style the label for the checkboxes so they are larger and look clickable. A custom set of icons are added to the label to provide additional visual feedback.

The checkbox controls below use standard input/label markup, but are styled to be more touch-friendly. The styled control you see is actually the label element, which sits over the real input, so if images fail to load, you'll still have a functional control. In most browsers, clicking the label automatically triggers a click on the input, but we've had to trigger the update manually for a few mobile browsers that don't do this natively. On the desktop, these controls are keyboard and screen-reader accessible.

To create a single checkbox, add an input with a type="checkbox" attribute and a corresponding label. If the input isn't wrapped in its corresponding label, be sure to set the for attribute of the label to match the id of the input so they are semantically associated.

1
2
3
4
 
<label><input type="checkbox" name="checkbox-0"> I agree </label>
 
<input type="checkbox" name="checkbox-1" id="checkbox-1" class="custom">
<label for="checkbox-1">I agree</label>

The above snippets will produce two basic checkboxes. The default styles will set the width of the element to 100% of the parent container.

Mini version

For a more compact version that is useful in toolbars and tight spaces, add the data-mini="true" attribute to the element to create a mini version.

1
2
 
<input type="checkbox" name="checkbox-mini" id="checkbox-mini-1" class="custom" data-mini="true">
<label for="checkbox-mini-1">I agree</label>

This will produce a checkbox that is not as tall as the standard version and has a smaller text size.

Field containers & Legends

Optionally wrap the checkboxes in a container with class ui-field-contain to help visually group it in a longer form.

Note: The data- attribute data-role="fieldcontain" is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class ui-field-contain instead.

Because checkboxes use the label element for the text displayed next to the checkbox form element, we recommend wrapping the checkbox in a fieldset element that has a legend which acts as the title for the question. Add the data-role="controlgroup" attribute to the fieldset so it can be styled in a parallel way as text inputs, selects or other form elements.

1
2
3
4
5
6
7
 
<div class="ui-field-contain">
  <fieldset data-role="controlgroup">
    <legend>Agree to the terms:</legend>
    <input type="checkbox" name="checkbox-2" id="checkbox-2" class="custom">
    <label for="checkbox-2">I agree</label>
  </fieldset>
</div>

Vertically grouped checkboxes

Typically, there are multiple checkboxes listed under a question title. To visually integrate multiple checkboxes into a grouped button set, the framework will automatically remove all margins between buttons and round only the top and bottom corners of the set if there is a data-role="controlgroup" attribute on the fieldset.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
 
<div class="ui-field-contain">
  <fieldset data-role="controlgroup">
    <legend>Choose as many snacks as you'd like:</legend>
      <input type="checkbox" name="checkbox-1a" id="checkbox-1a" class="custom">
      <label for="checkbox-1a">Cheetos</label>
 
      <input type="checkbox" name="checkbox-2a" id="checkbox-2a" class="custom">
      <label for="checkbox-2a">Doritos</label>
 
      <input type="checkbox" name="checkbox-3a" id="checkbox-3a" class="custom">
      <label for="checkbox-3a">Fritos</label>
 
      <input type="checkbox" name="checkbox-4a" id="checkbox-4a" class="custom">
      <label for="checkbox-4a">Sun Chips</label>
    </fieldset>
</div>

Horizontal toggle sets

Checkboxes can also be used for grouped button sets where more than one button can be selected at once, such as the bold, italic and underline button group seen in word processors. To make a horizontal button set, add the data-type="horizontal" to the fieldset.

1
2
3
4
5
6
7
8
9
10
11
12
13
 
<div class="ui-field-contain">
  <fieldset data-role="controlgroup" data-type="horizontal">
    <legend>Font styling:</legend>
    <input type="checkbox" name="checkbox-6" id="checkbox-6" class="custom">
    <label for="checkbox-6">b</label>
 
    <input type="checkbox" name="checkbox-7" id="checkbox-7" class="custom">
    <label for="checkbox-7"><em>i</em></label>
 
    <input type="checkbox" name="checkbox-8" id="checkbox-8" class="custom">
    <label for="checkbox-8">u</label>
  </fieldset>
</div>

The framework will float the labels so they sit side-by-side on a line, hide the checkbox icons and only round the left and right edges of the group.

Radio buttons

Radio buttons are used to provide a list of options where only a single item can be selected. Traditional desktop radio buttons are not optimized for touch input so jQuery Mobile styles the label for the radio buttons so they are larger and look clickable. A custom set of icons are added to the label to provide additional visual feedback.

The radio button controls below use standard input/label markup, but are styled to be more touch-friendly. The styled control you see is actually the label element, which sits over the real input, so if images fail to load, you'll still have a functional control. In most browsers, clicking the label automatically triggers a click on the input, but we've had to trigger the update manually for a few mobile browsers that don't do this natively. On the desktop, these controls are keyboard and screen-reader accessible.

Vertically grouped radio buttons

To create a set of radio buttons, add an input with a type="radio" attribute and a corresponding label. Set the for attribute of the label to match the id of the input so they are semantically associated.

The label element is displayed next to the radio form element. Wrap the radio buttons in a fieldset element that has a legend which acts as the title for the question.

To visually integrate multiple radio buttons into a vertically grouped button set, the framework will automatically remove all margins between buttons and round only the top and bottom corners of the set if there is a data-role="controlgroup" attribute on the container.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
 
<fieldset data-role="controlgroup">
  <legend>Choose a pet:</legend>
  <input type="radio" name="radio-choice" id="radio-choice-1" value="choice-1" checked="checked">
  <label for="radio-choice-1">Cat</label>
 
  <input type="radio" name="radio-choice" id="radio-choice-2" value="choice-2">
  <label for="radio-choice-2">Dog</label>
 
  <input type="radio" name="radio-choice" id="radio-choice-3" value="choice-3">
  <label for="radio-choice-3">Hamster</label>
 
  <input type="radio" name="radio-choice" id="radio-choice-4" value="choice-4">
  <label for="radio-choice-4">Lizard</label>
</fieldset>

This will produce a vertically grouped radio button set. The default styles set the width of the button group to 100% of the parent container and stacks the label on a separate line.

Mini version

For a more compact version that is useful in toolbars and tight spaces, add the data-mini="true" attribute to the element to create a mini version.

1
2
3
4
5
6
7
8
9
10
 
<fieldset data-role="controlgroup" data-mini="true">
  <input type="radio" name="radio-mini" id="radio-mini-1" value="choice-1" checked="checked">
  <label for="radio-mini-1">Credit</label>
 
  <input type="radio" name="radio-mini" id="radio-mini-2" value="choice-2">
  <label for="radio-mini-2">Debit</label>
 
  <input type="radio" name="radio-mini" id="radio-mini-3" value="choice-3">
  <label for="radio-mini-3">Cash</label>
</fieldset>

This will produce a radio button that is not as tall as the standard version and has a smaller text size.

Field containers

Optionally wrap the radio buttons in a container with class ui-field-contain to help visually group it in a longer form.

Note: The data- attribute data-role="fieldcontain" is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class ui-field-contain instead.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
 
<div class="ui-field-contain">
  <fieldset data-role="controlgroup">
    <legend>Choose a pet:</legend>
    <input type="radio" name="radio-choice-2" id="radio-choice-1" value="choice-1" checked="checked">
    <label for="radio-choice-1">Cat</label>
 
    <input type="radio" name="radio-choice-2" id="radio-choice-2" value="choice-2">
    <label for="radio-choice-2">Dog</label>
 
    <input type="radio" name="radio-choice-2" id="radio-choice-3" value="choice-3">
    <label for="radio-choice-3">Hamster</label>
 
    <input type="radio" name="radio-choice-2" id="radio-choice-4" value="choice-4">
    <label for="radio-choice-4">Lizard</label>
  </fieldset>
</div>

Horizontal radio button sets

Radio buttons can also be used for grouped button sets where only a single button can be selected at once, such as a view switcher control. To make a horizontal radio button set, add the data-type="horizontal" to the fieldset.

1
 
<fieldset data-role="controlgroup" data-type="horizontal">

The labels float so they sit side-by-side on a line. The radio button icons are hidden and only the left and right edges of the group are rounded.

Providing pre-rendered markup

You can improve the load time of your page by providing the markup that the checkboxradio widget would normally create during its initialization.

By providing this markup yourself, and by indicating that you have done so by setting the attribute data-enhanced="true", you instruct the checkboxradio widget to skip these DOM manipulations during instantiation and to assume that the required DOM structure is already present.

When you provide such pre-rendered markup you must also set all the classes that the framework would normally set, and you must also set all data attributes whose values differ from the default to indicate that the pre-rendered markup reflects the non-default value of the corresponding widget option.

The checkboxradio widget wraps the input element in a div and prepends the label element to the div.

In the example below, pre-rendered markup for a checkbox is provided. The attribute data-corners="false" is explicitly specified, since the absence of the ui-corner-all class on the label element indicates that the value of the "corners" widget option is to be false.

1
2
3
4
 
<div class="ui-checkbox">
  <label for="my-checkbox" class="ui-btn ui-btn-inherit ui-btn-icon-left ui-checkbox-off">My Checkbox</label>
  <input type="checkbox" id="my-checkbox" data-corners="false" data-enhanced="true"></input>
</div>

Options

defaults 

Type: Boolean
Default: false
Seting this option to true indicates that other widgets options have default values and causes jQuery Mobile's widget autoenhancement code to omit the step where it retrieves option values from data attributes. This can improve startup time.

This option is also exposed as a data attribute: data-defaults="true".

Code examples:

Initialize the checkboxradio with the defaults option specified:

1
2
3
 
$( ".selector" ).checkboxradio({
  defaults: true
});

Get or set the defaults option, after initialization:

1
2
3
4
5
 
// Getter
var defaults = $( ".selector" ).checkboxradio( "option", "defaults" );
 
// Setter
$( ".selector" ).checkboxradio( "option", "defaults", true );

disabled 

Type: Boolean
Default: false
Disables the checkboxradio if set to true.

This option is also exposed as a data attribute: data-disabled="true".

Code examples:

Initialize the checkboxradio with the disabled option specified:

1
2
3
 
$( ".selector" ).checkboxradio({
  disabled: true
});

Get or set the disabled option, after initialization:

1
2
3
4
5
 
// Getter
var disabled = $( ".selector" ).checkboxradio( "option", "disabled" );
 
// Setter
$( ".selector" ).checkboxradio( "option", "disabled", true );

enhanced 

Type: Boolean
Default: false
Indicates that the markup necessary for a checkboxradio widget has been provided as part of the original markup.

This option is also exposed as a data attribute: data-enhanced="true".

Code examples:

Initialize the checkboxradio with the enhanced option specified:

1
2
3
 
$( ".selector" ).checkboxradio({
  enhanced: true
});

Get or set the enhanced option, after initialization:

1
2
3
4
5
 
// Getter
var enhanced = $( ".selector" ).checkboxradio( "option", "enhanced" );
 
// Setter
$( ".selector" ).checkboxradio( "option", "enhanced", true );

iconpos 

Type: String
Default: "left"
Allows you to specify on which side of the checkbox or radio button the checkmark/radio icon will appear.

This option is also exposed as a data attribute: data-iconpos="right".

Code examples:

Initialize the checkboxradio with the iconpos option specified:

1
2
3
 
$( ".selector" ).checkboxradio({
  iconpos: "right"
});

Get or set the iconpos option, after initialization:

1
2
3
4
5
 
// Getter
var iconpos = $( ".selector" ).checkboxradio( "option", "iconpos" );
 
// Setter
$( ".selector" ).checkboxradio( "option", "iconpos", "right" );

initSelector 

Type: Selector
Default: See below

The default initSelector for the checkboxradio widget is:

1
 
"input:not( :jqmData(role='flipswitch' ) )[type='checkbox'],input[type='radio']:not( :jqmData(role='flipswitch' ))"

Note: This option is deprecated in 1.4.0 and will be removed in 1.5.0.
As of jQuery Mobile 1.4.0, the initSelector is no longer a widget option. Instead, it is declared directly on the widget prototype. Thus, you may specify a custom value by handling the mobileinit event and overwriting the initSelector on the prototype:

1
2
3
 
$( document ).on( "mobileinit", function() {
  $.mobile.checkboxradio.prototype.initSelector = "div.custom";
});

Note: Remember to attach the mobileinit handler after you have loaded jQuery, but before you load jQuery Mobile, because the event is triggered as part of jQuery Mobile's loading process.

The value of this option is a jQuery selector string. The framework selects elements based on the value of this option and instantiates checkboxradio widgets on each of the resulting list of elements.

(version deprecated: 1.4.0)

mini 

Type: Boolean
Default: null (false)
If set to true, this will display a more compact version of the checkboxradio that uses less vertical height by applying the ui-mini class to the outermost element of the checkboxradio widget.

This option is also exposed as a data attribute: data-mini="true".

wrapperClass 

Type:
Default: null
It is difficult to write custom CSS for the wrapper div around the native input element generated by the framework. This option allows you to specify one or more space-separated class names to be added to the wrapper div element by the framework.

This option is also exposed as a data attribute: data-wrapper-class="custom-class".

Code examples:

Initialize the checkboxradio with the wrapperClass option specified:

1
2
3
 
$( ".selector" ).checkboxradio({
  wrapperClass: "custom-class"
});

Get or set the wrapperClass option, after initialization:

1
2
3
4
5
 
// Getter
var wrapperClass = $( ".selector" ).checkboxradio( "option", "wrapperClass" );
 
// Setter
$( ".selector" ).checkboxradio( "option", "wrapperClass", "custom-class" );

Methods

destroy()Returns: jQuery (plugin only)

Removes the checkboxradio functionality completely. This will return the element back to its pre-init state.
  • This method does not accept any arguments.
Code examples:

Invoke the destroy method:

1
 
$( ".selector" ).checkboxradio( "destroy" );

disable()Returns: jQuery (plugin only)

Disables the checkboxradio.
  • This method does not accept any arguments.
Code examples:

Invoke the disable method:

1
 
$( ".selector" ).checkboxradio( "disable" );

enable()Returns: jQuery (plugin only)

Enables the checkboxradio.
  • This method does not accept any arguments.
Code examples:

Invoke the enable method:

1
 
$( ".selector" ).checkboxradio( "enable" );

option( optionName )Returns: Object

Gets the value currently associated with the specified optionName.
  • optionName
    Type: String
    The name of the option to get.
Code examples:

Invoke the method:

1
 
var isDisabled = $( ".selector" ).checkboxradio( "option", "disabled" );

option()Returns: PlainObject

Gets an object containing key/value pairs representing the current checkboxradio options hash.
  • This signature does not accept any arguments.
Code examples:

Invoke the method:

1
 
var options = $( ".selector" ).checkboxradio( "option" );

option( optionName, value )Returns: jQuery (plugin only)

Sets the value of the checkboxradio option associated with the specified optionName.
  • optionName
    Type: String
    The name of the option to set.
  • value
    Type: Object
    A value to set for the option.
Code examples:

Invoke the method:

1
 
$( ".selector" ).checkboxradio( "option", "disabled", true );

option( options )Returns: jQuery (plugin only)

Sets one or more options for the checkboxradio.
  • options
    Type: Object
    A map of option-value pairs to set.
Code examples:

Invoke the method:

1
 
$( ".selector" ).checkboxradio( "option", { disabled: true } );

refresh()Returns: jQuery (plugin only)

update the checkboxradio.

If you manipulate a checkboxradio via JavaScript, you must call the refresh method on it to update the visual styling.

  • This method does not accept any arguments.
Code examples:

Invoke the refresh method:

1
 
$( ".selector" ).checkboxradio( "refresh" );

1

Invoke the refresh method after changing the checked property:

1
 
$( ".selector" ).prop( "checked", true ).checkboxradio( "refresh" );

Events

create( event, ui )Type: checkboxradiocreate

Triggered when the checkboxradio is created.

Note: The ui object is empty but included for consistency with other events.

Code examples:

Initialize the checkboxradio with the create callback specified:

1
2
3
 
$( ".selector" ).checkboxradio({
  create: function( event, ui ) {}
});

Bind an event listener to the checkboxradiocreate event:

1
 
$( ".selector" ).on( "checkboxradiocreate", function( event, ui ) {} );

Examples:

A basic example of a checkbox in a fieldcontainer

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>checkboxradio demo</title>
  <link rel="stylesheet" href="//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.css">
  <script src="//code.jquery.com/jquery-1.10.2.min.js"></script>
  <script src="//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.js"></script>
</head>
<body>
 
<div data-role="page" id="page1">
  <div data-role="header">
    <h1>jQuery Mobile Example</h1>
  </div>
  <div role="main" class="ui-content">
    <div class="ui-field-contain">
      <form>
        <fieldset data-role="controlgroup">
          <legend>Agree to the terms:</legend>
          <input type="checkbox" name="checkbox-2" id="checkbox-2" class="custom">
          <label for="checkbox-2">I agree</label>
        </fieldset>
      </form>
    </div>
  </div>
</div>
 
</body>
</html>

Demo:

A basic example of vertically grouped radio buttons

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>checkboxradio demo</title>
  <link rel="stylesheet" href="//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.css">
  <script src="//code.jquery.com/jquery-1.10.2.min.js"></script>
  <script src="//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.js"></script>
</head>
<body>
 
<div data-role="page" id="page1">
  <div data-role="header">
    <h1>jQuery Mobile Example</h1>
  </div>
  <div role="main" class="ui-content">
    <form>
      <fieldset data-role="controlgroup">
        <legend>Choose a pet:</legend>
        <input type="radio" name="radio-choice" id="radio-choice-1" value="choice-1" checked="checked">
        <label for="radio-choice-1">Cat</label>
 
        <input type="radio" name="radio-choice" id="radio-choice-2" value="choice-2">
        <label for="radio-choice-2">Dog</label>
 
        <input type="radio" name="radio-choice" id="radio-choice-3" value="choice-3">
        <label for="radio-choice-3">Hamster</label>
 
        <input type="radio" name="radio-choice" id="radio-choice-4" value="choice-4">
        <label for="radio-choice-4">Lizard</label>
      </fieldset>
    </form>
  </div>
</div>
 
<script></script>
 
</body>
</html>

Demo: