Controlgroup Widget

Categories: Widgets

Controlgroup Widgetversion added: 1.3

Description: Groups buttons together.

QuickNavExamples

Options

Methods

Events

Occasionally, you may want to visually group a set of buttons to form a single block that looks contained like a navigation component. To get this effect, wrap a set of buttons in a container with the data-role="controlgroup" attribute — the framework will create a vertical button group, remove all margins and drop shadows between the buttons, and only round the first and last buttons of the set to create the effect that they are grouped together.

1
2
3
4
5
 
<div data-role="controlgroup">
  <a href="#" class="ui-btn ui-corner-all">Yes</a>
  <a href="#" class="ui-btn ui-corner-all">No</a>
  <a href="#" class="ui-btn ui-corner-all">Maybe</a>
</div>

This will result in the following button group:

By adding the data-type="horizontal" attribute to the controlgroup container, you can swap to a horizontal-style group that floats the buttons side-by-side and sets the width to only be large enough to fit the content. (Be aware that these will wrap to multiple lines if the number of buttons or the overall text length is too wide for the screen.)

Horizontal grouped buttons:

Labels

If you use a controlgroup for input, button or select buttons we recommend wrapping them in a fieldset element that has a legend which acts as the combined label for the group. The label elements of each individual button in the group will be hidden for styling purposes, and are only accessible by screen readers. Using the label as a wrapper around the form element prevents the framework from hiding it, so you have to use the for attribute to associate the label with the input.

Options

corners 

Type: Boolean
Default: true

Sets whether to draw the controlgroup with rounded corners.

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

Code examples:

Initialize the controlgroup with the corners option specified:

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

Get or set the corners option, after initialization:

1
2
3
4
5
 
// Getter
var corners = $( ".selector" ).controlgroup( "option", "corners" );
 
// Setter
$( ".selector" ).controlgroup( "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 controlgroup with the defaults option specified:

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

Get or set the defaults option, after initialization:

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

disabled 

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

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

Code examples:

Initialize the controlgroup with the disabled option specified:

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

Get or set the disabled option, after initialization:

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

excludeInvisible 

Type: Boolean
Default: true

Sets whether to exclude invisible children in the assignment of rounded corners.

When set to false, all children of a controlgroup are taken into account when assigning rounded corners, including hidden children. Thus, if, for example, the controlgroup's first child is hidden, the controlgroup will, in effect, not have rounded corners on the top edge.

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

Code examples:

Initialize the controlgroup with the excludeInvisible option specified:

1
2
3
 
$( ".selector" ).controlgroup({
  excludeInvisible: false
});

Get or set the excludeInvisible option, after initialization:

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

initSelector 

Type: Selector
Default: See below

The default initSelector for the controlgroup widget is:

1
 
":jqmData(role='controlgroup')"

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.controlgroup.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 controlgroup 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 controlgroup that uses less vertical height by applying the ui-mini class to the outermost element of the controlgroup widget.

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

shadow 

Type: Boolean
Default: false

Sets whether a drop shadow is drawn around the controlgroup.

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

Code examples:

Initialize the controlgroup with the shadow option specified:

1
2
3
 
$( ".selector" ).controlgroup({
  shadow: true
});

Get or set the shadow option, after initialization:

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

theme 

Type: String
Default: null, inherited from parent
Sets the color scheme (swatch) for the controlgroup. 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 controlgroup with the theme option specified:

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

Get or set the theme option, after initialization:

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

type 

Type: String
Default: vertical

Sets whether children should be stacked on top of each other or next to each other. If set to "horizontal", the children of the controlgroup will be stacked next to each other.

This option is also exposed as a data attribute: data-type="horizontal".

Code examples:

Initialize the controlgroup with the type option specified:

1
2
3
 
$( ".selector" ).controlgroup({
  type: "horizontal"
});

Get or set the type option, after initialization:

1
2
3
4
5
 
// Getter
var type = $( ".selector" ).controlgroup( "option", "type" );
 
// Setter
$( ".selector" ).controlgroup( "option", "type", "horizontal" );

Methods

container()Returns: jQuery (plugin only)

Obtain the container element within which the controlgroup's child elements are to be placed.
1
 
$( ".selector" ).controlgroup( "container" );
  • This method does not accept any arguments.
Code examples:

Invoke the container method:

1
 
$( ".selector" ).controlgroup( "container" );

destroy()Returns: jQuery (plugin only)

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

disable()Returns: jQuery (plugin only)

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

Invoke the disable method:

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

enable()Returns: jQuery (plugin only)

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

Invoke the enable method:

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

option()Returns: PlainObject

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

Invoke the method:

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

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

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

option( options )Returns: jQuery (plugin only)

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

Invoke the method:

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

Events

create( event, ui )Type: controlgroupcreate

Triggered when the controlgroup is created.

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

Code examples:

Initialize the controlgroup with the create callback specified:

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

Bind an event listener to the controlgroupcreate event:

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

Example:

A basic example of a controlgroup.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>controlgroup 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 role="main" class="ui-content">
    <div data-role="controlgroup">
      <a href="#" class="ui-btn ui-corner-all">Yes</a>
      <a href="#" class="ui-btn ui-corner-all">No</a>
      <a href="#" class="ui-btn ui-corner-all">Maybe</a>
    </div>
  </div>
</div>
 
</body>
</html>

Demo: