jQuery UI 1.10 Upgrade Guide

link Overview

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

link API Redesigns

jQuery UI 1.10 introduces API redesigns for Dialog and Progressbar. You can read about the API redesign process on the jQuery UI Blog. Although the redesigns introduce breaking changes, 1.10 maintains full compatibility with the 1.9 API by default. This is accomplished by rebuilding the 1.9 API on top of the 1.10 API. The default behavior for all 1.10 releases will be to simultaneously use the 1.9 and 1.10 APIs, deferring to the 1.9 API if there is a conflict. If you would like to load just the 1.10 API without the 1.9 API, you can set the $.uiBackCompat flag to false.

1
2
3
 
<script src="jquery.js"></script>
<script>$.uiBackCompat = false;</script>
<script src="jquery-ui.js"></script>

This will prevent the initialization of the back-compat layer, allowing you to use the 1.10 API in cases where there is a conflict with the 1.9 API.

link Preparing for jQuery UI 1.11

The API redesigns deprecate some functionality, which will be removed in 1.11. You don't have to wait for the 1.11.0 release in order to find out if your code will work when the 1.9 APIs are removed. You can use the $.uiBackCompat flag to test this with any 1.10 release.

If you find a regression from the 1.9 API, please report it in the bug tracker. Even though the 1.9 API is deprecated, it's important for 1.10 releases not to regress so that users are encouraged to upgrade even if they're not ready to use the new APIs. Note that most 1.8 APIs which were deprecated in 1.9 were removed in 1.10 and will not exist, regardless of the $.uiBackCompat flag.

link Removed support for IE6

IE6 usage has dropped to a low enough point that jQuery UI no longer finds it necessary to support. As of 1.10.0, some portions of jQuery UI may not work properly in IE6. If you need to continue to support IE6, use the latest jQuery UI 1.9 release.

link Improved download builder

The download builder once again supports downloading two versions. You can now download the latest stable release and one major version back. Also, as a result of GitHub removing support for uploads, we now host the download zips for all versions at http://jqueryui.com/download/all/.

link Core

link Removed $.ui.isOver() and $.ui.isOverAxis() methods

(#8891) The $.ui.isOver() and $.ui.isOverAxis() methods were written for specific plugins and had less-than-obvious APIs. They have been deprecated for a while, and as such have been removed.

link Removed $.ui.contains() method; use $.contains()

(#8902) The $.ui.contains() method has been removed in favor of $.contains(). See the 1.9 deprecation notice for full details.

link Accordion

link Added ability to add/remove panels

(#4672) The refresh method will now recognize panels that have been added or removed. This brings accordion in line with tabs and other widgets that parse the markup to find changes.

1
2
3
4
5
6
7
8
9
 
// Initialize the accordion
$( "#accordion" ).accordion();
 
// Add a new header and panel
$( "<h3>New Panel</h3>" ).appendTo( "#accordion" );
$( "<div>jQuery UI sure is awesome!</div>" ).appendTo( "#accordion" );
 
// Refresh the accordion
$( "#accordion" ).accordion( "refresh" );

link Removed changestart event; use beforeActivate

(#6841) The changestart event has been removed in favor of beforeActivate. See the 1.9 deprecation notice for full details.

link Removed change event; use activate

(#6843) The change event has been removed in favor of activate. See the 1.9 deprecation notice for full details.

link Removed resize method; use refresh

(#6839) The resize method has been removed in favor of refresh. See the 1.9 deprecation notice for full details.

link Removed animated option; use animate

(#8601) The animated option has been removed in favor of animate. See the 1.9 deprecation notice for full details.

link Removed icons.headerSelected option; use icons.activeHeader

(#6835) The icons.headerSelected option has been removed in favor of icons.activeHeader. See the 1.9 deprecation notice for full details.

link Removed autoHeight, clearStyle, and fillSpace options; use heightStyle

(#5868) (#5872) The autoHeight, clearStyle, and fillSpace options have been removed in favor of heightStyle. See the 1.9 deprecation notice for full details.

link Removed activate method; use active option

(#6837) The activate method has been removed in favor of the active option. See the 1.9 deprecation notice for full details.

link Removed navigation and navigationFilter options

(#5870) The navigation and navigationFilter options have been removed. See the 1.9 deprecation notice for full details.

link Removed support for non-number/falsey values for active option

(#6853) The active option must be set to a number, or false to collapse. Negative numbers will now select panels starting from the last panel, similar to .eq(). See the 1.9 deprecation notice for full details.

link Deprecated content property in create event; renamed to panel

(#8998) The content property in the create event has been renamed to panel for consistency with other events. You should replace all uses of the content property with the panel property.

Old API:

1
2
3
4
5
6
7
8
 
$( "#accordion" ).accordion({
    create: function( event, ui ) {
        // Active panel
        ui.content
        // Active header
        ui.header
    }
});

New API:

1
2
3
4
5
6
7
8
9
 
$( "#accordion" ).accordion({
    create: function( event, ui ) {
        // Active panel
        // CHANGED (previously content)
        ui.panel
        // Active header
        ui.header
    }
});

Note: This change was originally missed during the API redesign and did not occur until 1.10.1. As a result, the old API is not hidden behind the $.uiBackCompat flag and the new API is not available in 1.10.0.

The content property will be removed in 1.11.

link Autocomplete

link Removed item.autocomplete data; use ui-autocomplete-item

(#8156) Each menu item stores its source object using .data(). This data is no longer stored with a key of item.autocomplete, but rather ui-autocomplete-item. See the 1.9 deprecation notice for full details.

link Dialog

link Added appendTo option

(#7948) Previously, dialogs had always been appended to the body to ensure they were the last element in the DOM to avoid conflicts with other stacking contexts. However, in order to allow more flexibility and simplify the stacking logic, an appendTo option has been added which defaults to the body. Check out the API documentation for more information.

link Added ability to specify which element to focus on open

(#4731) When a dialog opens, it gains focus so that the user may immediately start interacting with it. This also allows assistive technologies, such as screen readers, to announce the dialog. The logic for which element gains focus has traditionally been whichever element is found first in the following categories: tabbable elements within the content area, tabbable elements within the button pane, the close button, and finally the dialog itself as a fallback. Starting with 1.10.0, if there is an element inside the content area with the autofocus attribute, that element will gain focus; if there is none, then the previous logic will be used.

link Added support for icons in buttons

(#6830) The buttons option now supports two more properties to control the use of icons. An icons hash may be provided, with primary and/or secondary properties, and the showText property may be set to false to hide text when using an icon. For more information on using icons, see the button documentation.

link Restore focus on close

(#8730) In addition to having more control over which element gains focus when the dialog opens, the dialog will also remember which element had focus outside of the dialog. When the dialog is closed, focus will be restored to the element that had focus immediately before the dialog opened. This will put the user back in the same state they were in, again resulting in improved usability and accessibility.

link Deprecated array and string notations for position option

(#8824) Over time, the dialog widget accrued a few different ways to specify the opening position. You could specify a string, such as "left center"; or an array of pixels, such as [ 200, 100 ]; or an object that would get passed to the position utility. Since we have standardized on using the position utility in all widgets, we have deprecated the string and array notations.

Old API:

1
2
3
 
$( "#dialog" ).dialog({
    position: "right bottom"
});

New API:

1
2
3
4
5
6
 
$( "#dialog" ).dialog({
    position: {
        my: "right bottom",
        at: "right bottom"
    }
});

Old API:

1
2
3
 
$( "#dialog" ).dialog({
    position: [ 200, 100 ]
});

New API:

1
2
3
4
5
6
 
$( "#dialog" ).dialog({
    position: {
        my: "left top",
        at: "left+200 top+100"
    }
});

link Removed stack option

(#8722) Dialogs previously supported a stack option, which determined whether dialogs should move to the top when focused. As this should always be the case, the option has been removed.

link Removed zIndex option

(#8729) Similar to the stack option, the zIndex option is unnecessary with a proper stacking implementation. The z-index is defined in CSS and stacking is now controlled by ensuring the focused dialog is the last "stacking" element in its parent.

link Changed title option from HTML to text

(#6016) Dialog titles are controlled either via the title option or the title attribute on the content element. The title has previously been set as HTML, but since titles are generally plain text, this could easily cause a scripting vulnerability for users who don't realize the value is being set as HTML. As a result, titles are now set as text. If you need to add custom formatting to your dialog titles, you can override the _title() method on the dialog.

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 Progressbar

link Added support for indeterminate progressbars

(#7624) The progressbar widget now supports an indeterminate state for situations where the current status of an action cannot be determined. Simply set the value option to false to create an indeterminate progressbar. You can seamlessly transition from an indeterminate progressbar to a determinate progressbar just by changing the value from false to a number.

link Resizable

link Added support for complex markup in handles

(#8756) While most users let the resizable widget generate handles automatically, it is possible to create your own handles in the markup prior to initialization. However, until now the handles were required to be a single element. As of 1.10.0, custom handles can contain complex markup, nesting elements as deep as you wish within the handle.

link Spinner

link Trigger all events for programmatic steps

(#8901) In 1.9.x, the spinner widget did not trigger start, spin, or stop events when programmatically stepping via the stepUp(), stepDown(), pageUp(), or pageDown() methods (only change was triggered). Starting with 1.10.0, all events are triggered, matching the behavior of a user-initiated step.

link Tabs

link Removed fx option; use show and hide

(#8320) The fx option has been removed in favor of show and hide. See the 1.9 deprecation notice for full details.

link Removed ajaxOptions and cache options; use beforeLoad event

(#7147) The ajaxOptions and cache options have been removed in favor of the beforeLoad event. See the 1.9 deprecation notice for full details.

link Removed url method; use aria-controls attribute

(#7148) The url method has been removed in favor of the aria-controls attribute. See the 1.9 deprecation notice for full details.

link Removed use of title attribute; use aria-controls

(#7149) Use of the title attribute to specify a tab panel has been removed in favor of aria-controls. See the 1.9 deprecation notice for full details.

link Removed abort method

(#7150) The abort method was removed in favor of storing a reference to the jqXHR object in the beforeLoad event. See the 1.9 deprecation notice for full details.

link Removed spinner option

(#7151) The spinner options has been removed. See the 1.9 deprecation notice for full details.

link Removed selected option; use active

(#7152) The selected option has been removed in favor of active. See the 1.9 deprecation notice for full details.

link Removed select event; use beforeActivate

(#7154) The select event has been removed in favor of beforeActivate. See the 1.9 deprecation notice for full details.

link Removed show event; use activate

(#7155) The show event has been removed in favor of activate. See the 1.9 deprecation notice for full details.

link Removed select method; use active option

(#7156) The select event has been removed in favor of the active option. See the 1.9 deprecation notice for full details.

link Removed add and remove methods; use refresh

(#7158) The add and remove methods have been removed in favor of refresh. See the 1.9 deprecation notice for full details.

link Removed idPrefix, tabTemplate, and panelTemplate options; use refresh method

(#7157) The idPrefix, tabTemplate, and panelTemplate options have been removed in favor of the refresh method. See the 1.9 deprecation notice for full details.

link Removed enable and disable events

(#7160) The enable and disable event have been removed. See the 1.9 deprecation notice for full details.

link Removed length method

(#7161) The length method has been removed. See the 1.9 deprecation notice for full details.

(#7162) The cookie option has been removed. See the 1.9 deprecation notice for full details.

link Changed load event to pass jQuery objects

(#8731) The load event now passes jQuery objects instead of DOM elements for consistency with other plugins in jQuery UI.

Old API:

1
2
3
4
5
 
$( "#tabs" ).tabs({
    load: function( event, ui ) {
        $( ui.panel ).addClass( "loaded" );
    }
});

New API:

1
2
3
4
5
 
$( "#tabs" ).tabs({
    load: function( event, ui ) {
        ui.panel.addClass( "loaded" );
    }
});

link Tooltip

link Changed default content option from HTML to text

(#8861) The default content option uses the title attribute as the content for the tooltip. Previously the value was set as HTML, but it is now set as text. This fixes a security vulnerability as well as bringing the functionality in line with how the attribute is meant to be used.

link Widget

link Removed use of metadata plugin

(#7192) Use of the metadata plugin for widget options has been removed. See the 1.9 deprecation notice for full details.

link Removed widgetBaseClass property; use widgetFullName

(#8155) The widgetBaseClass property has been removed in favor of widgetFullName. See the 1.9 deprecation notice for full details.

link Removed data fallbacks for widget names

(#8801) Widgets used to store their instances in .data() using just the plugin name as a key. The instances are now stored using the widget namespace as well. For example, the dialog widget is now stored in ui-dialog instead of dialog. See the 1.9 deprecation notice for full details.

link Effects

link Removed support for effects in $.effects[]; use $.effects.effect[]

(#7115) Support for defining effects directly on $.effects has been removed in favor of defining effects on $.effects.effect. The API for new effects is slightly different, so make sure to read the 1.9 deprecation notice for full details.