Load ThemeRoller into this page! (Only works in Firefox and if this page was served through HTTP.)

jQuery Expandable plugin

Default Expandable (zero configuration)


With jQuery UI setting up the expandable should be really pretty easy. First you need to get your HTML template for the expandable widget in place. The template will be converted into an expandable when calling the expandable method.

<div id="box-1" class="expandable-1"> <div class="ui-expandable-title">Your Title</div> Your Content here. </div>

If you want to set the title programmatically, or need no title at all, just leave out the title div (.ui-expandable-title).

Before you can set up your Expandables be sure to load all the relevant files in the HTML head:

<link rel="stylesheet" href="ui.expandable.css" type="text/css" /> <link rel="stylesheet" href="jquery/ui.core.css" type="text/css" /> <link rel="stylesheet" href="jquery/ui.theme.css" type="text/css" /> <script type="text/javascript" src="jquery/jquery-1.4.4.min.js"></script> <script type="text/javascript" src="ui.expandable.js"></script>

The files in blue are required for the Expandable to function. The rest can be done without (see tab: 'Without jQuery UI). If the expandable does not look or behave as expected double-check if the paths are correct and the scripts and style sheets are really being loaded. You can use Firebug's Net tab for that.

Now you're all set up to initalize your Expandable:

<script> jQuery(function($) { $(".expandable-1").expandable(); }); </script>

The result should look like this:

Your Title
Your Content here.

The content in the expandable has a default padding, you can easily override this in your own style sheet. See the CSS tab for more info.

The simplest 'option' is to leave out the title, as described in the previous tab:

<div id="box-1" class="expandable-1"> Your Content here. </div>

Which looks like this:

Your content

You can set the title through options too. This will override any title you set in the template.

There are many more options. To cover them all let's first have a look at the defaults:

$.fn.expandable.defaults = { startopen: false, title: null, tooltip: "Click to expand", uiIconClosed: "ui-icon-triangle-1-e", uiIconOpen: "ui-icon-triangle-1-s", animationClose: { height: "hide" }, animationOpen: { height: "show" }, duration: "normal", easing: "swing", open: null, closed: null, opening: null, closing: null, headerClick: null, headerHover: function(over, event) { if ( over ) { $(this) .removeClass("ui-state-default") .addClass("ui-state-hover"); } else { $(this) .removeClass("ui-state-hover") .addClass("ui-state-default"); } }, extraicon: null, extraiconClick: null, extraiconHover: function(over, event, options) { if ( over ) { $(this).addClass("ui-state-hover"); } else { $(this).removeClass("ui-state-hover"); } }, iconMarginTop: null, iconMarginBottom: null };

whether to initially show the content. Boolean
the title in the header of the expandable. String
the tooltip that appears when you mouseover the header. String
the CSS class for the left icon in closed state. String
the CSS class for the left icon in open state. String
properties for the jQuery animate function when closing. Object
properties for the jQuery animate function when opening. Object
the duration for the jQuery animate function. Number, String
the easing to apply in the jQuery animate function. String
callback when opening has completed. Function
callback when closing has completed. Function
callback before opening. Function
callback before closing. Function
callback when header is clicked. Function
callback when mouse enters and leaves the header. Function

the CSS class for the right icon. String
callback when right icon is clicked. Function
callback when mouse enters and leaves the right icon. Function

margin on header icons if innerHeight of the header is 0. Number
margin on header icons if innerHeight of the header is 0. Number

Here is an example of an expandable with most options customized:

custom tooltip
start opened or closed
callbacks for: closing, opening, open, closed, headerClick, headerHover, extraiconClick and extraiconHover
extra icon on the right (.ui-expandable-extraicon)
title set programmatically
using icons from jQuery UI (1.6rc4+)
customized animation (but same as default, in this example)

Other options

Three more options exist to manipulate the expandable or get information from it:

$(selector).expandable("open"); $(selector).expandable("close"); $(selector).expandable("state"); $(selector).expandable("destroy");

"Open" and "close" do exactly what you'd expect from them, they open and close the expandable, firing all the callbacks except "headerClick".
"State" returns one of the strings "opening", "open", "closing" and "closed".
"Destroy" restores the HTML code to its pre-expandable state.

Currently the widget relies, but does not depend on jQuery UI. This means it can also be used without the UI files. For the most part, you just have to style the widget with your own CSS to set borders, paddings, etc. This may be what you want anyway. Be aware however, that future releases (> v0.5) probably will depend on jQuery UI.

These are the classes used in the expandable:

<div class="ui-expandable ui-widget"> <div class="ui-state-default ui-widget-header"> <div class="ui-expandable-icon ui-icon [ui-icon-circle-triangle-s]"></div> <div class="ui-expandable-title">Title</div> <div class="ui-expandable-extraicon"> <span class="ui-icon [ui-icon-close]"></span> </div> </div> <div class="ui-widget-content ui-helper-clearfix"> Content </div> </div>

By default the content in the expandable has the following padding:

.ui-expandable .ui-widget-content { padding: 11px 18px 13px 18px; }

For the rest, please have a look at the ui.expandable.css file. It's short and easy to understand. It's no big deal to override the default styles with your own style sheet. And using the callbacks it's easy to dynamically add and remove custom interaction classes in the structure as well.

Below you you have an example of an expandable that has almost all of the CSS rules overridden by local, static rules in this document.

trickier, nested
content with a floated image and
reversed icons (also set in CSS)


If you're not using jQuery UI and having trouble with content containers ignoring the height of floats try the rule below.
If using jQuery UI the class/rule '.ui-helper-clearfix' fixes this for you (in different, possibly better way). Note: this problem is not specific to the Expandable Widget itself but to CSS.

info: http://www.quirksmode.org/css/clearing.html

#your-selector.ui-expandable .ui-widget-content { overflow:hidden; width: 100%; }
Work in progress...

To do: One-time options, icon bug

  • If the content of the unfinished expandable is visible on page load (maybe your scripts are doing a lot of work) you can put a display:none on the expandable. It will as soon as it's finished.
  • Some of your questions may be answered when you look at the code of this page. (eg. title, options, callbacks)