Flipswitch Widget

Categories: Widgets

Flipswitch Widgetversion added: 1.4

Description: Creates a flipswitch widget

QuickNavExamples

Options

Methods

Events

Flip switches

The flip switch is an alternative look to the checkbox or the two-option select menu. It can be toggled by a click or a swipe.

To create a flip switch add the attribute data-role="flipswitch" to a checkbox input or to a select which has two option values.

Theming

The flipswitch widget uses the jQuery Mobile CSS framework to style its look and feel. If flipswitch specific styling is needed, the following CSS class names can be used for overrides or as keys for the classes option:

  • ui-flipswitch: The outermost container for flipswitch. Additionally, ui-flipswitch-active class will be applied in case flipswitch is in active
    • ui-flipswitch-on: On state label of flipswitch
    • ui-flipswitch-off: Off state label of flipswitch
    • ui-flipswitch-input: Input checkbox element for flipswitch

Checkbox-based flipswitch

Use the following markup to create a flipswitch based on a checkbox input:

1
2
3
4
5
6
 
<fieldset>
  <div data-role="fieldcontain">
    <label for="checkbox-based-flipswitch">Checkbox-based:</label>
    <input type="checkbox" id="checkbox-based-flipswitch" data-role="flipswitch">
  </div>
</fieldset>
The labels for the flipswitch are controlled by the onText and offText options.

Select-based flipswitch

You can also create a flipswitch based on a select element:

1
2
3
4
5
6
7
8
9
 
<fieldset>
  <div data-role="fieldcontain">
    <label for="select-based-flipswitch">Select-based:</label>
    <select id="select-based-flipswitch" data-role="flipswitch">
      <option value="leave">Bye</option>
      <option value="arrive">Hi</option>
    </select>
  </div>
</fieldset>
The labels for the flipswitch are controlled by the labels of the select element's option elements. The first option is used for the inactive, "off" state, and the second option is used for the active, "on" state.

Custom labels

You can customize the labels displayed by the flipswitch widget either using the onText and offText options if the widget is based on a checkbox, or using the text inside the first two option elements if the widget is based on a select.

The location of the text inside the two labels is specified manually in the flipswitch widget's structural CSS. Thus, if you use labels that are longer than "On" and "Off", you may have to override the default text placement using the following custom CSS:

1
2
3
4
5
6
 
.ui-flipswitch .ui-btn.ui-flipswitch-on {
  text-indent: -2.6em;
}
.ui-flipswitch .ui-flipswitch-off {
  text-indent: 1em;
}

Depending on your choice of labels, you may also have to provide custom CSS to override the default width for the flipswitch:

1
2
3
4
5
6
7
8
9
10
11
12
13
 
.ui-flipswitch {
  width: 5.875em;
}
.ui-flipswitch.ui-flipswitch-active {
  padding-left: 4em;
  width: 1.875em;
}
@media (min-width: 28em) {
  // Repeated from rule .ui-flipswitch above
  .ui-field-contain > label + .ui-flipswitch {
    width: 1.875em;
  }
}

Providing pre-rendered markup

You can improve the load time of your page by providing the markup that the flipswitch 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 flipswitch 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 flipswitch widget adds a wrapper div around the input. In addition to the original element, the wrapper also contains two span elements where the two labels are stored. The first span is styled as a button with the text for the active state appearing outside the button's bounding box to the left. To make the flipswitch reachable by tabbing, you can add the tabindex="1" attribute to the first span.

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

1
2
3
4
5
 
<div class="ui-flipswitch ui-shadow-inset ui-bar-inherit">
  <span tabindex="1" class="ui-flipswitch-on ui-btn ui-shadow ui-btn-inherit">On</span>
  <span class="ui-flipswitch-off">Off</span>
  <input type="checkbox" data-role="flipswitch" data-enhanced="true" data-corners="false" name="flip-checkbox" class="ui-flipswitch-input">
</div>

Options

classes 

Type: Object
Default: 
{
        "ui-flipswitch": "ui-shadow-inset ui-corner-all",
        "ui-flipswitch-on": "ui-shadow"
      }

Specify additional classes to add to the widget's elements. Any of classes specified in the Theming section can be used as keys to override their value. To learn more about this option, check out the learn article about the classes option.

Code examples:

Initialize the flipswitch with the classes option specified, changing the theming for the ui-flipswitch class:

1
2
3
4
5
 
$( ".selector" ).flipswitch({
  classes: {
    "ui-flipswitch": "highlight"
  }
});

Get or set a property of the classes option, after initialization, here reading and changing the theming for the ui-flipswitch class:

1
2
3
4
5
 
// Getter
var themeClass = $( ".selector" ).flipswitch( "option", "classes.ui-flipswitch" );
 
// Setter
$( ".selector" ).flipswitch( "option", "classes.ui-flipswitch", "highlight" );

corners 

Type: Boolean
Default: true
Applies the theme button border-radius if set to true.

This option is also exposed as a data attribute: data-corners="false".

Code examples:

Initialize the flipswitch with the corners option specified:

1
2
3
 
$( ".selector" ).flipswitch({
  corners: false
});

Get or set the corners option, after initialization:

1
2
3
4
5
 
// Getter
var corners = $( ".selector" ).flipswitch( "option", "corners" );
 
// Setter
$( ".selector" ).flipswitch( "option", "corners", false );

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 flipswitch with the defaults option specified:

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

Get or set the defaults option, after initialization:

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

disabled 

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

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

Code examples:

Initialize the flipswitch with the disabled option specified:

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

Get or set the disabled option, after initialization:

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

enhanced 

Type: Boolean
Default: false
Indicates that the markup necessary for a flipswitch 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 flipswitch with the enhanced option specified:

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

Get or set the enhanced option, after initialization:

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

mini 

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

Note: mini option is deprecated in 1.5 and will be removed in 1.6

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

offText 

Type: String
Default: "Off"

When the flipswitch widget is based on a checkbox rather than a select the value of this option is used as the label for the "Off" state.

This option is also exposed as a data attribute: data-off-text="Go"

Code examples:

Initialize the flipswitch with the offText option specified:

1
2
3
 
$( ".selector" ).flipswitch({
  offText: "Go"
});

Get or set the offText option, after initialization:

1
2
3
4
5
 
// Getter
var offText = $( ".selector" ).flipswitch( "option", "offText" );
 
// Setter
$( ".selector" ).flipswitch( "option", "offText", "Go" );

onText 

Type: String
Default: "On"

When the flipswitch widget is based on a checkbox rather than a select the value of this option is used as the label for the "On" state.

This option is also exposed as a data attribute: data-on-text="Go"

Code examples:

Initialize the flipswitch with the onText option specified:

1
2
3
 
$( ".selector" ).flipswitch({
  onText: "Stay"
});

Get or set the onText option, after initialization:

1
2
3
4
5
 
// Getter
var onText = $( ".selector" ).flipswitch( "option", "onText" );
 
// Setter
$( ".selector" ).flipswitch( "option", "onText", "Stay" );

theme 

Type: String
Default: null, inherited from parent
Sets the color scheme (swatch) for the flipswitch widget. It accepts a single letter from a-z that maps to the swatches included in your theme.

Possible values: swatch letter (a-z).

This option is also exposed as a data attribute: data-theme="b".

Code examples:

Initialize the flipswitch with the theme option specified:

1
2
3
 
$( ".selector" ).flipswitch({
  theme: "b"
});

Get or set the theme option, after initialization:

1
2
3
4
5
 
// Getter
var theme = $( ".selector" ).flipswitch( "option", "theme" );
 
// Setter
$( ".selector" ).flipswitch( "option", "theme", "b" );

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 flipswitch with the wrapperClass option specified:

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

Get or set the wrapperClass option, after initialization:

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

Methods

destroy()Returns: jQuery (plugin only)

Removes the flipswitch 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" ).flipswitch( "destroy" );

disable()Returns: jQuery (plugin only)

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

Invoke the disable method:

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

enable()Returns: jQuery (plugin only)

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

Invoke the enable method:

1
 
$( ".selector" ).flipswitch( "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" ).flipswitch( "option", "disabled" );

option()Returns: PlainObject

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

Invoke the method:

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

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

Sets the value of the flipswitch 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" ).flipswitch( "option", "disabled", true );

option( options )Returns: jQuery (plugin only)

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

Invoke the method:

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

refresh()Returns: jQuery (plugin only)

update the flipswitch.

If you manipulate a flipswitch 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" ).flipswitch( "refresh" );

1

Events

create( event, ui )Type: flipswitchcreate

Triggered when the flipswitch is created.

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

Code examples:

Initialize the flipswitch with the create callback specified:

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

Bind an event listener to the flipswitchcreate event:

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

Example:

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
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>flipswitch demo</title>
  <link rel="stylesheet" href="//code.jquery.com/mobile/1.5.0-alpha.1/jquery.mobile-1.5.0-alpha.1.min.css">
  <script src="//code.jquery.com/jquery-3.2.1.min.js"></script>
  <script src="//code.jquery.com/mobile/1.5.0-alpha.1/jquery.mobile-1.5.0-alpha.1.min.js"></script>
</head>
<body>
<div data-role="header">
    <h1>jQuery Mobile Example</h1>
  </div>
  <div role="main" class="ui-content">
    <div class="ui-field-contain">
      <form>
        <div data-role="fieldcontain">
          <label for="checkbox-based-flipswitch-0">Checkbox-based:</label>
          <input type="checkbox" id="checkbox-based-flipswitch-0" data-role="flipswitch">
        </div>
      </form>
    </div>
  </div>  
</body>
</html>

Demo: