jQuery UI 1.10 Upgrade Guide
- API Redesigns
- Added ability to add/remove panels
- Removed changestart event; use beforeActivate
- Removed change event; use activate
- Removed resize method; use refresh
- Removed animated option; use animate
- Removed icons.headerSelected option; use icons.activeHeader
- Removed autoHeight, clearStyle, and fillSpace options; use heightStyle
- Removed activate method; use active option
- Removed navigation and navigationFilter options
- Removed support for non-number/falsey values for active option
- Deprecated content property in create event; renamed to panel
- Removed fx option; use show and hide
- Removed ajaxOptions and cache options; use beforeLoad event
- Removed url method; use aria-controls attribute
- Removed use of title attribute; use aria-controls
- Removed abort method
- Removed spinner option
- Removed selected option; use active
- Removed select event; use beforeActivate
- Removed show event; use activate
- Removed select method; use active option
- Removed add and remove methods; use refresh
- Removed idPrefix, tabTemplate, and panelTemplate options; use refresh mehod
- Removed enable and disable events
- Removed length method
- Removed cookie option
- Changed load event to pass jQuery objects
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
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
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
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/.
$.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.
$.ui.contains() method; use
link Added ability to add/remove panels
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.
changestart event; use
change event; use
resize method; use
animated option; use
icons.headerSelected option; use
fillSpace options; use
activate method; use
link Removed support for non-number/falsey values for
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
See the 1.9 deprecation notice for full details.
content property in create event; renamed to
content property in the create event has been renamed to
consistency with other events. You should replace all uses of the
property with the
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.
content property will be removed in 1.11.
item.autocomplete data; use
Each menu item stores its source object using
.data(). This data is no longer
stored with a key of
item.autocomplete, but rather
See the 1.9 deprecation notice for full details.
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,
appendTo option has been added which defaults to the body. Check out the
API documentation for more
link Added ability to specify which element to focus on open
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
attribute, that element will gain focus; if there is none, then the previous
logic will be used.
link Added support for icons in buttons
buttons option now supports two more properties to control the use of icons.
icons hash may be provided, with
showText property may be set to false to hide text when using an icon.
For more information on using icons, see the
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
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,
[ 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
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.
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
title option from HTML to text
Dialog titles are controlled either via the
title option or the
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.
offset option; use
link Added support for indeterminate progressbars
The progressbar widget now supports an indeterminate state for situations where
the current status of an action cannot be determined. Simply set the
false to create an indeterminate progressbar. You can seamlessly
transition from an indeterminate progressbar to a determinate progressbar just
by changing the
false to a number.
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 Trigger all events for programmatic steps
In 1.9.x, the spinner widget did not trigger
when programmatically stepping via the
pageDown() methods (only
change was triggered). Starting with 1.10.0, all
events are triggered, matching the behavior of a user-initiated step.
fx option; use
cache options; use
url method; use
link Removed use of
title attribute; use
selected option; use
select event; use
show event; use
select method; use
remove methods; use
panelTemplate options; use
load event to pass jQuery objects
load event now passes jQuery objects instead of DOM elements for consistency
with other plugins in jQuery UI.
link Changed default
content option from HTML to text
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 Removed use of metadata plugin
widgetBaseClass property; use
link Removed data fallbacks for widget names
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
See the 1.9 deprecation notice for full details.
link Removed support for effects in
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.