W3cubDocs

/jQuery Mobile

Collapsible Widget

Collapsible Widgetversion added: 1.0

Description: Creates a collapsible block of content

QuickNavExamples

Options

Methods

Events

Collapsible content

Note: Collapsible is deprecated as of version 1.5 and will be removed in version 1.6. Use accordion in place of collapsible.

To create a collapsible block of content, create a container and add the data-role="collapsible" attribute. Using the data-content-theme attribute allows you to set a theme for the content of the collapsible.

Directly inside this container, add any header (H1-H6) or legend element. The framework will style the header to look like a clickable button and add a "+" icon to the left to indicate it's expandable.

After the header, add any HTML markup you want to be collapsible. The framework will wrap this markup in a container that will be hidden/shown when the heading is clicked.

By default, the content will be collapsed.

<div data-role="collapsible">
  <h3>I'm a header</h3>
  <p>I'm the collapsible content. By default I'm closed, but you can click the header to open me.</p>
</div>

This code will create a collapsible widget like this:

Theming

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

  • ui-collapsible: The outermost container for collapsible. Contains additional classes of ui-collapsible-inset, ui-collapsible-themed-content and ui-collapsible-collapsed by default unless options to set them false are added.
    • ui-collapsible-heading: Always visible part of collapsible, which is clicked to open it. Additionally contains ui-collapsible-heading-collapsed class when the collapsible is closed.
      • ui-collapsible-heading-toggle: Toggler for collapsible
        • ui-collapsible-heading-status: Status text of the toggler
    • ui-collapsible-content: Content of the collapsible. Additionally contains ui-collapsible-content-collapsed class in case the content is collapsed.

Initially expanded collapsibles

When you add the data-collapsed="false" attribute to the wrapper the collapsible will initially be expanded.

<div data-role="collapsible" data-collapsed="false">

This code will create a collapsible widget like this:

Non-inset collapsibles

By default collapsibles have an inset appearance. To make them full width without corner styling add the data-inset="false" attribute to the element.

<div data-role="collapsible" data-inset="false">

This code will create a non-inset collapsible:

Mini collapsibles

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.

<div data-role="collapsible" data-mini="true">

This code will create a mini collapsible widget:

Custom icons

The default icon of collapsible headings can be overridden by using the data-collapsed-icon and data-expanded-icon attributes. The example below uses data-collapsed-icon="arrow-r" and data-expanded-icon="arrow-d".

Icon positioning

The default icon positioning of collapsible headings can be overridden by using the data-iconpos attribute. The example below uses data-iconpos="right".

Theming collapsible content

Collapsible content is minimally styled - we add only a bit of margin between the bar and content, and the header adopts the default theme styles of the container within which it sits.

To provide a stronger visual connection between the collapsible header and content, add the data-content-theme attribute to the wrapper and specify a theme swatch letter. This applies the border and background color of the swatch to the content block and changes the corner rounding to square off the bottom of the header and round the bottom of the content block instead to visually group these elements.

<div data-role="collapsible" data-content-theme="b">
  <h3>Header</h3>
  <p>I'm the collapsible content with a themed content block set to "b".</p>
</div>

Theming collapsible headers

To set the theme on a collapsible header button, add the data-theme attribute to the wrapper and specify a swatch letter. Note that you can mix and match swatch letters between the header and content with these theme attributes.

<div data-role="collapsible" data-theme="b" data-content-theme="b">
  <h3>Header swatch B</h3>
  <p>I'm the collapsible content with a themed content block set to "b".</p>
</div>

Nested Collapsibles

Collapsibles can be nested inside each other if needed. In this example, we're setting the content theme to provide clearer visual connection between the levels.

Collapsible sets (accordions)

It's possible to combine multiple collapsibles into a grouped set that acts like an accordion widget.

Providing pre-rendered markup

You can improve the load time of your page by providing the markup that the collapsible 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 collapsible 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 collapsible widget creates an anchor from the heading element and wraps the rest of the children of the outermost widget in a div that will serve as the container for the collapsible content.

In the example below, pre-rendered markup for a collapsible is provided. The attribute data-collapsed-icon="arrow-r" is explicitly specified, since the use of theui-icon-arrow-r class on the anchor element indicates that the value of the "collapsedIcon" widget option is to be "arrow-r".

<div data-role="collapsible" data-enhanced="true" class="ui-collapsible ui-collapsible-inset ui-corner-all ui-collapsible-collapsed" data-collapsed-icon="arrow-r">
  <h2 class="ui-collapsible-heading ui-collapsible-heading-collapsed">
    <a href="#" class="ui-collapsible-heading-toggle ui-btn ui-btn-icon-left ui-icon-arrow-r">
      Pre-rendered collapsible
      <span class="ui-collapsible-heading-status"> click to expand contents</span>
    </a>
  </h2>
  <div class="ui-collapsible-content ui-collapsible-content-collapsed" aria-hidden="true">
    <p>This is the collapsible-content</p>
  </div>
</div>

Options

classes

Type: Object
Default: 
{}

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 collapsible with the classes option specified, changing the theming for the ui-collapsible class:

$( ".selector" ).collapsible({
  classes: {
    "ui-collapsible": "highlight"
  }
});

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

// Getter
var themeClass = $( ".selector" ).collapsible( "option", "classes.ui-collapsible" );
 
// Setter
$( ".selector" ).collapsible( "option", "classes.ui-collapsible", "highlight" );

collapseCueText

Type: String
Default: " click to collapse contents"
This text is used to provide audible feedback for users with screen reader software.

If the value is unset for an individual collapsible container, but that container is part of a collapsible set, then the value is inherited from the parent collapsible set.

This option is also exposed as a data attribute: data-collapse-cue-text=" collapse with a click".

Code examples:

Initialize the collapsible with the collapseCueText option specified:

$( ".selector" ).collapsible({
  collapseCueText: " collapse with a click"
});

Get or set the collapseCueText option, after initialization:

// Getter
var collapseCueText = $( ".selector" ).collapsible( "option", "collapseCueText" );
 
// Setter
$( ".selector" ).collapsible( "option", "collapseCueText", " collapse with a click" );

collapsed

Type: Boolean
Default: true
When false, the container is initially expanded with a minus icon in the header.

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

Code examples:

Initialize the collapsible with the collapsed option specified:

$( ".selector" ).collapsible({
  collapsed: false
});

Get or set the collapsed option, after initialization:

// Getter
var collapsed = $( ".selector" ).collapsible( "option", "collapsed" );
 
// Setter
$( ".selector" ).collapsible( "option", "collapsed", false );

collapsedIcon

Type: String or Boolean
Default: "plus"
Sets the icon for the header of the collapsible container when in a collapsed state.

If the value is unset for an individual collapsible container, but that container is part of a collapsible set, then the value is inherited from the parent collapsible set.

This option is also exposed as a data attribute: data-collapsed-icon="arrow-r".

Multiple types supported:
  • String: The name of the icon you wish to use.
  • Boolean: In addition to an icon name, you can also set this option to false. In that case, the collapsible will not have an icon in either the expanded or collapsed state. Add data-collapsed-icon="false" to the collapsible widget to set the option to false via the data attribute.
Code examples:

Initialize the collapsible with the collapsedIcon option specified:

$( ".selector" ).collapsible({
  collapsedIcon: "arrow-r"
});

Get or set the collapsedIcon option, after initialization:

// Getter
var collapsedIcon = $( ".selector" ).collapsible( "option", "collapsedIcon" );
 
// Setter
$( ".selector" ).collapsible( "option", "collapsedIcon", "arrow-r" );

contentTheme

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

If the value is unset for an individual collapsible container, but that container is part of a collapsible set, then the value is inherited from the parent collapsible set.

Possible values: swatch letter (a-z).

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

Code examples:

Initialize the collapsible with the contentTheme option specified:

$( ".selector" ).collapsible({
  contentTheme: "b"
});

Get or set the contentTheme option, after initialization:

// Getter
var contentTheme = $( ".selector" ).collapsible( "option", "contentTheme" );
 
// Setter
$( ".selector" ).collapsible( "option", "contentTheme", "b" );

corners

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

If the value is unset for an individual collapsible container, but that container is part of a collapsible set, then the value is inherited from the parent collapsible set.

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

Code examples:

Initialize the collapsible with the corners option specified:

$( ".selector" ).collapsible({
  corners: false
});

Get or set the corners option, after initialization:

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

$( ".selector" ).collapsible({
  defaults: true
});

Get or set the defaults option, after initialization:

// Getter
var defaults = $( ".selector" ).collapsible( "option", "defaults" );
 
// Setter
$( ".selector" ).collapsible( "option", "defaults", true );

disabled

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

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

Code examples:

Initialize the collapsible with the disabled option specified:

$( ".selector" ).collapsible({
  disabled: true
});

Get or set the disabled option, after initialization:

// Getter
var disabled = $( ".selector" ).collapsible( "option", "disabled" );
 
// Setter
$( ".selector" ).collapsible( "option", "disabled", true );

enhanced

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

$( ".selector" ).collapsible({
  enhanced: true
});

Get or set the enhanced option, after initialization:

// Getter
var enhanced = $( ".selector" ).collapsible( "option", "enhanced" );
 
// Setter
$( ".selector" ).collapsible( "option", "enhanced", true );

expandCueText

Type: String
Default: " click to expand contents"
This text is used to provide audible feedback for users with screen reader software.

If the value is unset for an individual collapsible container, but that container is part of a collapsible set, then the value is inherited from the parent collapsible set.

This option is also exposed as a data attribute: data-expand-cue-text=" expand with a click".

Code examples:

Initialize the collapsible with the expandCueText option specified:

$( ".selector" ).collapsible({
  expandCueText: " expand with a click"
});

Get or set the expandCueText option, after initialization:

// Getter
var expandCueText = $( ".selector" ).collapsible( "option", "expandCueText" );
 
// Setter
$( ".selector" ).collapsible( "option", "expandCueText", " expand with a click" );

expandedIcon

Type: String
Default: "minus"
Sets the icon for the header of the collapsible container when in an expanded state.

If the value is unset for an individual collapsible container, but that container is part of a collapsible set, then the value is inherited from the parent collapsible set.

This option is also exposed as a data attribute: data-expanded-icon="arrow-d".

Code examples:

Initialize the collapsible with the expandedIcon option specified:

$( ".selector" ).collapsible({
  expandedIcon: "arrow-d"
});

Get or set the expandedIcon option, after initialization:

// Getter
var expandedIcon = $( ".selector" ).collapsible( "option", "expandedIcon" );
 
// Setter
$( ".selector" ).collapsible( "option", "expandedIcon", "arrow-d" );

heading

Type: String
Default: "h1,h2,h3,h4,h5,h6,legend"
Within the collapsible container, the first immediate child element that matches this selector will be used as the header for the collapsible.

This option is also exposed as a data attribute: data-heading=".mycollapsibleheading".

Code examples:

Initialize the collapsible with the heading option specified:

$( ".selector" ).collapsible({
  heading: ".mycollapsibleheading"
});

Get or set the heading option, after initialization:

// Getter
var heading = $( ".selector" ).collapsible( "option", "heading" );
 
// Setter
$( ".selector" ).collapsible( "option", "heading", ".mycollapsibleheading" );

iconpos

Type: String
Default: "left"
Positions the icon in the collapsible header.

If the value is unset for an individual collapsible container, but that container is part of a collapsible set, then the value is inherited from the parent collapsible set.

Possible values: left, right, top, bottom, none, notext.

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

Code examples:

Initialize the collapsible with the iconpos option specified:

$( ".selector" ).collapsible({
  iconpos: "right"
});

Get or set the iconpos option, after initialization:

// Getter
var iconpos = $( ".selector" ).collapsible( "option", "iconpos" );
 
// Setter
$( ".selector" ).collapsible( "option", "iconpos", "right" );

initSelector

Type: Selector
Default: See below

The default initSelector for the collapsible widget is:

":jqmData(role='collapsible')"

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:

$( document ).on( "mobileinit", function() {
  $.mobile.collapsible.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 collapsible widgets on each of the resulting list of elements.

(version deprecated: 1.4.0)

inset

Type: Boolean
Default: true
By setting this option to false the element will get a full width appearance without corners.

If the value is unset for an individual collapsible container, but that container is part of a collapsible set, then the value is inherited from the parent collapsible set.

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

Code examples:

Initialize the collapsible with the inset option specified:

$( ".selector" ).collapsible({
  inset: false
});

Get or set the inset option, after initialization:

// Getter
var inset = $( ".selector" ).collapsible( "option", "inset" );
 
// Setter
$( ".selector" ).collapsible( "option", "inset", false );

mini

Type: Boolean
Default: false
Sets the size of the element to a more compact, mini version.

If the value is unset for an individual collapsible container, but that container is part of a collapsible set, then the value is inherited from the parent collapsible set.

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

Code examples:

Initialize the collapsible with the mini option specified:

$( ".selector" ).collapsible({
  mini: true
});

Get or set the mini option, after initialization:

// Getter
var mini = $( ".selector" ).collapsible( "option", "mini" );
 
// Setter
$( ".selector" ).collapsible( "option", "mini", true );

theme

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

If the value is unset for an individual collapsible container, but that container is part of a collapsible set, then the value is inherited from the parent collapsible set.

Possible values: swatch letter (a-z).

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

Code examples:

Initialize the collapsible with the theme option specified:

$( ".selector" ).collapsible({
  theme: "b"
});

Get or set the theme option, after initialization:

// Getter
var theme = $( ".selector" ).collapsible( "option", "theme" );
 
// Setter
$( ".selector" ).collapsible( "option", "theme", "b" );

Methods

collapse()Returns: jQuery (plugin only)

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

Invoke the collapse method:

$( ".selector" ).collapsible( "collapse" );

destroy()Returns: jQuery (plugin only)

Removes the collapsible 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:

$( ".selector" ).collapsible( "destroy" );

disable()Returns: jQuery (plugin only)

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

Invoke the disable method:

$( ".selector" ).collapsible( "disable" );

enable()Returns: jQuery (plugin only)

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

Invoke the enable method:

$( ".selector" ).collapsible( "enable" );

expand()Returns: jQuery (plugin only)

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

Invoke the expand method:

$( ".selector" ).collapsible( "expand" );

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:

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

option()Returns: PlainObject

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

Invoke the method:

var options = $( ".selector" ).collapsible( "option" );

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

Sets the value of the collapsible 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:

$( ".selector" ).collapsible( "option", "disabled", true );

option( options )Returns: jQuery (plugin only)

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

Invoke the method:

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

Events

collapse( event, ui )Type: collapsiblecollapse

Triggered when a collapsible is collapsed

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

Code examples:

Initialize the collapsible with the collapse callback specified:

$( ".selector" ).collapsible({
  collapse: function( event, ui ) {}
});

Bind an event listener to the collapsiblecollapse event:

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

create( event, ui )Type: collapsiblecreate

Triggered when the collapsible is created.

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

Code examples:

Initialize the collapsible with the create callback specified:

$( ".selector" ).collapsible({
  create: function( event, ui ) {}
});

Bind an event listener to the collapsiblecreate event:

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

expand( event, ui )Type: collapsibleexpand

Triggered when a collapsible is expanded

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

Code examples:

Initialize the collapsible with the expand callback specified:

$( ".selector" ).collapsible({
  expand: function( event, ui ) {}
});

Bind an event listener to the collapsibleexpand event:

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

Example:

A basic example of a collapsible content block.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>collapsible 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 data-role="collapsible">
      <h3>I'm a header</h3>
      <p>I'm the collapsible content. By default I'm closed, but you can click the header to open me.</p>
    </div>
  </div>
</div>
 
</body>
</html>

Demo:

© The jQuery Foundation and other contributors
Licensed under the MIT License.
https://api.jquerymobile.com/collapsible