The iButton jQuery plug-in emulates the checkbox functionality found
on the iPhone. This plug-in was inspired by several other plug-ins—such
as Thomas Reynolds'
iphone-style-checkboxes. However, this plug-in attempts to combine the best
features of all of the various iPhone checkbox-style plug-ins and then add the
functionality that we felt was still missing.
In order to use the iButton plug-in, you need the following:
jQuery v1.2.6 (or higher)*
Optionally, you may also want to use:
jQuery Metadata Plug-in
The use of the Metadata plug-in allows you to define the options for your buttons
within the class attribute of the form element.
jQuery Easing Plug-in
The Easing Plug-in expands the options for easing in the animation of the sliding
* This plug-in may work with older versions of jQuery in the 1.2 family. If you try
using this with an older version of jQuery, you will need to include the
jquery.dimensions.js plug-in (as of jQuery v1.2.6 the jquery.dimensions.js
plug-in is included in the jQuery core.)
Works with checkboxes or radio elements
Full keyboard support
use the [TAB] key to move from field to field and use
the spacebar to toggle the status of the iButton (or use the arrow keys for
Custom event handlers
Detach iButton behavior from the element
when used with the jQuery Metadata Plug-in,
you can define the properties for your button completely within the class attribute of your
Enable/disable drag support
while the dragging behavior is intuitive on touch-based devices, it's not always be the best
or expected UI behavior and may cause some mouse users problems (NOTE: In order to help
differentiate between an intended mouse click or an actual drag event, we're developed
the clickOffset option. If the time (in milliseconds) is under this value (120ms by default)
it's assumed the user was attempting to click the button and not drag the handle.)
Single sprite image
easily change the look of your button by just replacing the image
use any labels you want for your buttons
Support for disabled buttons
Easing support for animations
To convert your checkbox (or radio) elements into iButton widgets, just invoke
the jQuery plug-in using the following syntax:
You can use any selector that will target checkboxes or radio elements on your page.
Optionally, you can target a form object (or any non-input element) to convert
all checkbox and radio elements contained in the element to an iButton:
This argument is optional and allows you to customize the
settings used for each instance of the plug-in. For a list of all available options,
see the Options section.
Now that we have a reference to the widget, we can invoke any of the public API calls.
Use the toggle() method to set the checked status of your input element. The value
argument is an optional boolean value that allows you to set the checked status to
either true or false. If the value argument is not supplied, the checked attribute
of your input element will be toggled from true to false (or vice versa.)
Use the disable() method to disable your button. This prevents the user being able to
interactive with the button. It allows disables the actual checkbox/radio element, and
disabled values are not submitted to the server on a form POST/GET operation.
Destroys the iButton widget. This restores the original checkbox/radio element
in the DOM.
This will repaint the button to match it's current checked status. This should only
be called if the checked attribute of the element has changed in some way out of your
control to synchronize the skin's state with the actual checkbox value. The correct
method of synchronizing the skin w/the element is to trigger the input's "change" event
after any manual update to it's value.
Returns a reference to the internal $.iButton object. This is for advanced usage only.
Examine the source code for uses of the $.iButton object.
There are a number of options available for customizing the look and feel of the iButton widget.
duration: 200 // the speed of the animation
, easing: "swing" // the easing animation to use
, labelOn: "ON" // the text to show when toggled on
, labelOff: "OFF" // the text to show when toggled off
, resizeHandle: "auto" // determines if handle should be resized
, resizeContainer: "auto" // determines if container should be resized
, enableDrag: true // determines if we allow dragging
, enableFx: true // determines if we show animation
, allowRadioUncheck: false // determine if a radio button should be able to
// be unchecked
, clickOffset: 120 // if millseconds between a mousedown & mouseup event this
// value, then considered a mouse click
// define the class statements
, className: "" // an additional class name to attach to the main container
, classContainer: "ibutton-container"
, classDisabled: "ibutton-disabled"
, classFocus: "ibutton-focus"
, classLabelOn: "ibutton-label-on"
, classLabelOff: "ibutton-label-off"
, classHandle: "ibutton-handle"
, classHandleMiddle: "ibutton-handle-middle"
, classHandleRight: "ibutton-handle-right"
, classHandleActive: "ibutton-active-handle"
, classPaddingLeft: "ibutton-padding-left"
, classPaddingRight: "ibutton-padding-right"
// event handlers
, init: null // callback that occurs when a iButton is initialized
, change: null // callback that occurs when the button state is changed
, click: null // callback that occurs when the button is clicked
, disable: null // callback that occurs when the button is disabled/enabled
, destroy: null // callback that occurs when the button is destroyed
<!---// load jQuery and the jQuery iButton Plug-in //--->
<!---// load the iButton CSS stylesheet //--->
<link type="text/css" href="./css/jquery.ibutton.css" rel="stylesheet" media="all" />
Before you can invoke an instance of the iButton widget, you must have one or more checkbox or radio elements on your page.
The next step is to actually create an instance of the iButton widget. You want to make
sure to initialize the widget after all the necessary DOM elements are available, which
makes the document.ready event a great place to initialize the widget.
This source code is provided as-is. At this time Giva is not offering direct support for this product.
If you are in need of assistance, post your question to one of the
jQuery Mailing Lists. Members of the Giva development
team actively participate on the jQuery Mailing lists, so if we see your question we will try our
best to respond.
Copyright 2011 Giva, Inc. (http://www.givainc.com/labs/)
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
The following download includes both uncompressed and minified versions of the plug-in and all the CSS and image files required to get you started. See the gettingstarted.htm file for usage instructions and a working example.