jQuery UI 1.11 Upgrade Guide

link Overview

This guide will assist in upgrading from jQuery UI 1.10.x to jQuery UI 1.11.x. All changes are listed below, organized by plugin, along with how to upgrade your code to work with jQuery UI 1.11.

link General changes

We made some changes that affect all source files and the ways you can access and load them in your applications. Our goal was to simplify where possible, while supporting more environments, specifically AMD and bower.

link Renamed files

We've dropped the "jquery.ui." prefix from all source files, so for example jquery.ui.accordion.js is now accordion.js. This makes usage with AMD easier (see below) and makes it easier to deal with the individual source files.

link AMD support

jQuery UI now supports AMD out-of-the-box. That means that you can specify "ui/autocomplete" as a dependency in your module, and an AMD script loader like require.js will resolve all the dependencies that the autocomplete widget has. You can learn more about using jQuery UI with AMD on learn.jquery.com.

link Bower support

jQuery UI now supports bower out-of-the-box. That means that you can install jQuery UI with bower by running bower install jquery-ui. You can learn more about using jQuery UI with bower on learn.jquery.com.

link Simplified custom and quick downloads

We've simplified our download packages. Instead of including all demos and source files, we now only include the concatenated files. The new structure looks like this:

.
├── images
│   └── ...
├── index.html
├── jquery-ui.css
├── jquery-ui.js
├── jquery-ui.min.css
├── jquery-ui.min.js
├── jquery-ui.structure.css
├── jquery-ui.structure.min.css
├── jquery-ui.theme.css
├── jquery-ui.theme.min.css
└── jquery.js

The jquery-ui.structure.css file provides the structural CSS rules (such as margins and positioning), and the jquery-ui.theme.css file contains the theming rules (such as backgrounds, colors, and fonts). This setup allows you to easily change themes by swapping in new jquery-ui.theme.css files. You can also build a theme from scratch by building on top of jquery-ui.structure.css. The jquery-ui.css file contains both jquery-ui.structure.css and jquery-ui.theme.css.

The index.html file contains a demo of each jQuery UI component and includes your selected theme. This is the same demo file that was included in previous versions of jQuery UI. jquery.js file, which is a copy of jQuery Core, also has not changed. jQuery UI 1.11 supports jQuery Core versions >= 1.6.

If you want the complete jQuery UI source files, demos, and tests, you can get them from https://github.com/jquery/jquery-ui/releases.

link Discontinued IE7 Support

As of this release we are no longer accepting bug reports for IE7 issues. We have also removed IE7 from our testing infrastructure. The IE7 workarounds are still present in the code, but we will remove them for jQuery UI 1.12.

link Core

link Deprecated .focus( n )

(#9646) The modified version of the jQuery Core .focus() method is now deprecated. jQuery UI was using this only in our dialog widget, where we've replaced the delayed focus call with a timeout.

Before:

1
 
element.focus( 1 );

After:

1
2
3
 
setTimeout(function() {
    element.focus();
});

link Deprecated .zIndex()

(#9061) .zIndex() is now deprecated in favor of the new .ui-front / appendTo logic used by all widgets that display an element on top of the page, like dialog and autocomplete.

This method was used by dialog, but because the dialog now has an appendTo option, this plugin method is no longer necessary. If you are using .zIndex(), or building a widget that must stack, check out our guide to create stacking elements with a ui-front class name and appendTo option.

link Removed $.ui.hasScroll()

(#9190) The deprecated and undocumented $.ui.hasScroll() method has been removed as it was only used by the resizable interaction.

link Removed $.ui.keyCode.NUMPAD_*.

(#9269) The following key code constants have been removed as they were not used by jQuery UI:

  • $.ui.keyCode.NUMPAD_ADD
  • $.ui.keyCode.NUMPAD_DECIMAL
  • $.ui.keyCode.NUMPAD_DIVIDE
  • $.ui.keyCode.NUMPAD_ENTER
  • $.ui.keyCode.NUMPAD_MULTIPLY
  • $.ui.keyCode.NUMPAD_SUBTRACT

link Accordion

link Removed content property in create event

(#8999) The deprecated content property in the create event was removed. The correct property to use is panel.

link Dialog

link Removed deprecated position handling

(#8825) The array and string notations for dialog's position option were deprecated in 1.10 and are now gone. Use the object notation of the position option instead.

link Switch back to shuffling z-index, but only look at ui-front siblings.

(#9166), (#9364) In 1.10, we rewrote dialog's moveToTop() method to move the DOM elements that shared the ui-front class name within the same parent. This solved a lot of problems that the previous, z-index based solution had, but it also created new issues due to moving the dialog around in the DOM.

In 1.11, we've kept the approach from 1.10, but also added back z-index handling, although in a restricted way. This solves problems with reloading of flash content and resetting of scroll positions, while still being more straightforward than the old approach.

This should be a pure bug fix, though if you use the dialog widget along with other elements that use z-index, you may need to test the stacking behavior when updating to 1.11.

link Position

link Removed offset option; use my or at

(#6982) The offset option has been removed in favor of providing offset information in my or at. See the 1.9 deprecation notice for full details.

link Added items option for better definition of menu items in non parent-child structures

(31e705a) A new items option was added to the menu widget. The option allows you to use markup other than the default, such as menu items that aren't immediate children of the menu container parent.

link Remove the requirement to use anchors in menu items

(3a61627) The menu widget no longer expects list items to contain anchors. Markup containing anchors will still work, although there may be styling issues. It's recommended to remove the anchors from your markup.

Old:

1
2
3
4
 
<ul id="menu">
    <li><a href="#">One</a></li>
    <li><a href="#">Two</a></li>
</ul>

New:

1
2
3
4
 
<ul id="menu">
    <li>One</li>
    <li>Two</li>
</ul>

The autocomplete and selectmenu widgets, which both use menu internally, were updated to remove the anchors.

link Simplify styling. Remove rounded corners, reduce spacing.

(9910e93) The structural styles of the menu widget have changed, including removing the rounded corners and reducing the spacing between menu items—which allows you to see more items without scrolling.

If you're using the menu widget, check if the new style fits into your page, and use the widget's theming hooks to customize the display to meet your needs.

link Slider

link Added Windows 8 touch support

(#9709) The slider widget now supports usage on Windows 8 touch devices.

link Switched handles from anchors to spans

(#9890) The slider widget now uses <span> elements instead of <a> elements for its handles to workaround an issue with usage in some single-page application frameworks. The handles still use the same ui-slider-handle class name as a styling hook.

link Spinner

link Added isValid() method

(#9542) The spinner widget now exposes an isValid() for determining whether the value of the spinner's input is valid. For example the following returns true:

1
2
3
 
$( "<input value='1'>" )
    .spinner({ step: 1 })
    .spinner( "isValid" );

And the following returns false:

1
2
3
 
$( "<input value='1'>" )
    .spinner({ step: 2 })
    .spinner( "isValid" );

link Widget

link $.widget() returns the widget's constructor.

(#9467) The $.widget() method now returns the widget's constructor instead of undefined. As an example, the following code creates a dialog extension, and then uses the new widget's constructor function to create an instance on a newly created <div>:

1
2
3
4
5
6
7
 
var redDialog = $.widget( "demo.redDialog", $.ui.dialog, {
    _create: function() {
        this._super();
        this.element.css( "color", "red" );
    }
});
redDialog( {}, "<div>jQuery UI Rocks!</div>" );

The same constructor functions are also returned when you use the jQuery UI widgets in an AMD context. For more details on how to use the widget's constructor functions, see our guide on using jQuery UI with AMD.

link Added instance() method on the bridge to return widget instance

(#9030) A new instance() method is now available on the plugin bridge. The method provides access to the widget's instance without going through .data().

Old:

1
2
3
 
var instance = $( "<div>" )
    .progressbar()
    .data( "ui-progressbar" );

New:

1
2
3
 
var instance = $( "<div>" )
    .progressbar()
    .progressbar( "instance" );

Unlike other plugin methods, the instance() method is safe to call on any element. If the element is not an instance of the given widget, the method returns undefined. For example the following code throws an error:

1
2
 
// Uncaught Error: cannot call methods on dialog prior to initialization; attempted to call method 'open'
$( "#not-a-dialog" ).dialog( "open" );

And this returns undefined:

1
 
$( "#not-a-dialog" ).dialog( "instance" );

link Changed enable() and disable() to use _setOptions() instead of _setOption()

(bc85742) Custom widgets can now override _setOptions() to implement custom handling for the disabled option. Because _setOptions() invokes _setOption(), existing code should not be affected.

link Stop setting ui-state-disabled and aria-disabled by default when the disabled option is set.

(#5973) (#5974) (#6039) The widget factory used to manage the ui-state-disabled class name and aria-disabled attribute as a widget's disabled option was toggled. That behavior has been removed as it created issues in some widgets where ui-state-disabled and aria-disabled did not make sense, such as the resizable widget.

If you have a themeable widget with a disabled option, you can manage ui-state-disabled and aria-disabled in the widget's _setOption() method. For instance this is how the progressbar widget handles its disabled option changing:

1
2
3
4
5
6
7
8
9
 
_setOption: function( key, value ) {
    ...
    if ( key === "disabled" ) {
        this.element
            .toggleClass( "ui-state-disabled", !!value )
            .attr( "aria-disabled", value );
    }
    this._super( key, value );
}

link Support events with dashes and colons

(#9708) The widget factory's _on() method now supports event names with dashes and colons. As an example the following creates a widget that listens for two events—one with a dash and one with a colon:

1
2
3
4
5
6
7
8
9
10
11
12
 
$.widget( "myNamespace.myWidget", {
    _create: function() {
        this._on({
            "foo-bar": function() {
                 console.log( "foo-bar" );
            },
            "foo:bar": function() {
                console.log( "foo:bar" );
            }
        });
    }
});

And the following creates an instance of the above widget and triggers the two events:

1
2
3
 
$( "<div>" ).myWidget()
    .trigger( "foo-bar" )
    .trigger( "foo:bar" );

link Effects

link Give puff and size effects their own files

(d0c613d) Previously, the puff, size, and scale effects shared a single file—jquery.ui.effect-scale.js. Now, each of these effects have their own files—effect-puff.js, effect-scale.js, and effect-size.js, respectively.