jQuery UI 1.12 Upgrade Guide

link Overview

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

link API Redesigns

jQuery UI 1.12 introduces API redesigns for Button, Buttonset, Dialog, Draggable, Droppable, Menu, Mouse, Resizable, Selectable, Sortable, Tabs, Tooltip, and Effects. You can read about the API redesign process on the jQuery UI Blog. Although the redesigns introduce breaking changes, 1.12 maintains a lot of compatibility with the 1.11 API by default. This is accomplished by rebuilding the 1.11 API on top of the 1.12 API. The default behavior for all 1.12 releases will be to simultaneously use the 1.11 and 1.12 APIs where possible. If you would like to load just the 1.12 API without the 1.11 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>

link Preparing for a future jQuery UI release

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

If you find a regression from the 1.11 API, please report it in the bug tracker. Even though the 1.11 API is deprecated, it's important for 1.12 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.10 APIs which were deprecated in 1.11 were removed in 1.12 and will not exist, regardless of the $.uiBackCompat flag.

link General changes

Independent of changes to specific components, this release removes support for IE7, modernizes the theming, including the default font-size, and improves support for AMD. The minimal jQuery version supported is now 1.7.0.

link Removed IE7 workarounds

(#9838) All IE7 workarounds have been removed from the source code. If you need continued IE7 support you can continue to use jQuery UI 1.11.x.

link Discontinued IE8, IE9, and IE10 support

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

link Font size changes

(#10131) jQuery UI themes used to be built around a body font-size of 62.5%, while widgets compensated for that with font-size of 1.1em. This rather small font-size default is now gone, assuming instead the default font-size of browsers.

link New default theme

(#10617) jQuery UI used to ship with a default theme called Smoothness. This theme is still available through ThemeRoller, but has been replaced by a new default theme called Base. This new theme has been modernized to get rid of background gradients, reduce rounded corners and use some colors outside of the greyscale range. In other words, it looks much better.

link Dropped support for jQuery 1.6

(#10723) jQuery UI no longer supports jQuery 1.6. The minimal supported version is now 1.7.0.

link Split core.js into small modules

(#9647) The "core" module that used to bundle various utilities is deprecated. Other source files no longer depend on core.js, which is now just a single define() call that specifies all the modules it previously bundled as dependencies.

link Moved widgets and effects source files into folders

(#13885) All widgets, including mouse.js (but excluding widget.js) were moved to a widgets subfolder, so for example, the source for the autocomplete widget is now ui/widgets/autocomplete.js. Similarly, all effects (except effect.js) were moved to an effects subfolder.

link Explicit CSS dependencies

In jQuery UI 1.11 we added support for AMD dependency management, but this applied only for JS files. CSS files still had to be managed manually (though download builder helps). In 1.12 all JS components now explicitly list their direct CSS dependencies, through structured source comments. For example, widgets/autocomplete.js has these comments:

1
2
3
 
//>>css.structure: ../../themes/base/core.css
//>>css.structure: ../../themes/base/autocomplete.css
//>>css.theme: ../../themes/base/theme.css

Download builder parses these to resolve each JS component's CSS dependencies. Other build tools like requirejs or webpack could also parse these (and make it reusable through plugins).

We hope to move to a format that resembles more of a standard eventually.

link Official package on npm

jQuery UI 1.12 is the first release officially published to npm as jquery-ui. The previous source repository only covered up to jQuery UI 1.10.5, but never had any of the 1.11 releases. Since the unofficial releases where heavily transformed and fundamentally incompatible with our source files and existing release process, we decided to publish 1.12 under the same name, with different folders and files. Accordingly, the npm releases of 1.12+ are not backwards compatible with the 1.10.x releases.

If you've used jQuery UI 1.10 via npm, make sure you don't use minor version ranges in your package.json. Before:

1
 
"jquery-ui": "^1.10.5"

After:

1
 
"jquery-ui": "1.10.x"

When you're ready to upgrade, you need to update your import paths.

Before:

1
 
var autocomplete = require( "jquery-ui/autocomplete" );

After:

1
 
var autocomplete = require( "jquery-ui/ui/widgets/autocomplete" );

If you've used require( "jquery-ui" ), then you need to replace that with individual imports.

If you're using browserify: The UMD headers we have aren't supported by browserify natively, and the deamdify plugin has a blocking bug. If you depend on that combination, please help fix that bug!

If you're using webpack or are considering it: You're good to go! It works, as shown in this demo.

link Core

link Removed .focus( delay )

(#9649) The deprecated .focus( delay ) method override has been removed. jQuery UI was using this only in our dialog widget, where we've replaced the delayed focus call with a timeout.

link Removed .zIndex()

(#9156) The deprecated .zIndex() method has been removed, in favor of the new .ui-front / appendTo stacking elements 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 Added .labels()

(#12475) This release introduces a new jQuery plugin method. .labels() finds all label elements associated with the first selected element.

link Mouse

link Deprecated distance and delay options

(#10615) Interactions should be instantaneous. These settings are typically used to prevent accidental drags, but a proper fix for that is to improve the user experience, e.g., using handles to avoid accidental drags.

Unlike most deprecated APIs which only remain for one version before being removed, the `distance` and `delay` options for each interaction won't be removed until the respective rewrites are included in a new version. As such, the `$.uiBackCompat` flag won't remove the options from the API.

link Autocomplete

link Require wrappers for each autocomplete menu item

See the changes in the menu widget.

link Button

The button widget underwent a rewrite in this release. Most notably, support for inputs of type checkbox and radio has been extracted into a standalone checkboxradio widget, and support for groups of buttons has been extracted into a more generic controlgroup widget. The remaining button widget also underwent some changes, simplifiying markup and options.

link Deprecated icons options in favor of icon and iconPosition

(#14744) The button widget used to have an icons option that supported primary and secondary properties, allowing up to two icons at once. This has been replaced by the icon option, which only allows a single icon, and the iconPosition option, which controls the placement of that one icon.

The equivalent of the old primary icons property is iconPosition: "beginning", while the equivalent of the old secondary icons property is iconPosition: "end". The new button also supports "top" and "bottom" for iconPosition, allowing the icon to be displayed above or below the button text.

To replace a primary icon:

Old:

1
2
3
4
5
 
$( "button" ).button( {
    icons: {
        primary: "ui-icon-lock"
    }
} );

New:

1
2
3
 
$( "button" ).button( {
    icon: "ui-icon-lock"
} );

Replacing a secondary icon also requires the iconPosition option:

Old:

1
2
3
4
5
 
$( "button" ).button( {
    icons: {
        secondary: "ui-icon-gear"
    }
} );

New:

1
2
3
4
 
$( "button" ).button( {
    icon: "ui-icon-gear",
    iconPosition: "end"
} );

Replacing a button with two icons can be accomplished by putting one icon in the markup:

Old:

1
 
<button>Click me</button>
1
2
3
4
5
6
 
$( "button" ).button( {
    icons: {
        primary: "ui-icon-lock",
        secondary: "ui-icon-gear"
    }
} );

New:

1
 
<button>Click me <span class="ui-icon ui-icon-gear"></span></button>
1
2
3
 
$( "button" ).button( {
    icon: "ui-icon-lock"
} );

link Deprecated text option in favor of showLabel

(#8203) This option was renamed for clarity, otherwise it hasn't changed.

Old:

1
2
3
4
5
6
7
8
 
$( "button" ).button( {
    text: false,
 
    // Still can't hide text without an icon
    icons: {
        primary: "ui-icon-gear"
    }
} );

New:

1
2
3
4
 
$( "button" ).button( {
    showLabel: false,
    icon: "ui-icon-gear"
} );

link Deprecated support for checkbox and radio types, in favor of checkboxradio widget

(#14746) With the introduction of the new checkboxradio widget, the button widget is no longer intended to be used as a toggle button. However, with back-compat enabled, the button widget will automatically detect if you're trying to create a button from a checkbox or radio button and call .checkboxradio() on those elements for you.

If you're using the button widget with one of these input types, replace it with the new checkboxradio widget:

Old:

1
 
$( "input[type=checkbox]" ).button();

New:

1
 
$( "input[type=checkbox]" ).checkboxradio();

Both old and new button and new checkboxradio support the label option, so you can keep using it without any changes. Checkboxradio doesn't have an equivalent of the text (old) or showLabel (new) option, it will always show the label. It also doesn't have an equivalent of the icons (Object, old) or icon (String, new) option, you can only turn the checkbox/radio icon on or off using the icon (Boolean) option. To replace a toggle button with a custom icon (no checkmark), turn off the icon and add a custom icon to the markup.

Old:

1
2
 
<input type="checkbox" id="metal">
<label for="metal">Metal Checkbox</label>
1
2
3
4
5
 
$( "input[type=checkbox]" ).button( {
    icons: {
        primary: "ui-icon-gear"
    }
} );

New:

1
2
 
<input type="checkbox" id="metal">
<label for="metal"><span class="ui-icon ui-icon-gear"></span> Metal Checkbox</label>
1
2
3
 
$( "input[type=checkbox]" ).checkboxradio({
    icon: false
});

link Buttonset

link Deprecated buttonset in favor of controlgroup

(#14747) The buttonset widget, bundled with the button widget, is now deprecated, in favor of the new controlgroup widget. If you were using buttonset without any options, migrating to controlgroup only requires a search-and-replace:

1
 
$( ".group" ).buttonset();

New:

1
 
$( ".group" ).controlgroup();

Controlgroup also has an items option, but the signature is different. Instead of listing only the selectors to match button widgets, all supported widgets now have a key in the items option, with the selectors as the value:

Old:

1
2
3
 
$( ".group" ).buttonset( {
    items: "button, span.btn"
} );

New:

1
2
3
4
5
 
$( ".group" ).controlgroup( {
    items: {
        button: "button, span.btn"
    }
} );

link Dialog

link Deprecated dialogClass in favor of classes.ui-dialog

(#12161) The dialogClass option is now deprecated. Use the new classes option with the ui-dialog property instead.

Old:

1
2
3
 
$( ".content" ).dialog( {
    dialogClass: "payment-dialog"
} );

New:

1
2
3
4
5
 
$( ".content" ).dialog( {
    classes: {
        "ui-dialog": "payment-dialog"
    }
} );

link Draggable

link Deprecated distance and delay options

See the notes for the mouse widget.

link Droppable

link Deprecated activeClass in favor of classes.ui-droppable-active

(#12162) The activeClass option is now deprecated. Use the new classes option with the ui-droppable-active property instead.

Old:

1
2
3
 
$( ".target" ).droppable( {
    activeClass: "drop-target"
} );

New:

1
2
3
4
5
 
$( ".target" ).droppable( {
    classes: {
        "ui-droppable-active": "drop-target"
    }
} );

link Deprecated hoverClass in favor of classes.ui-droppable-hover

(#12162) The hoverClass option is now deprecated. Use the new classes option with the ui-droppable-hover property instead.

Old:

1
2
3
 
$( ".target" ).droppable( {
    hoverClass: "drop-hover"
} );

New:

1
2
3
4
5
 
$( ".target" ).droppable( {
    classes: {
        "ui-droppable-hover": "drop-hover"
    }
} );

link Require wrappers for each menu item

(#10162) To resolve several styling issues, the menu widget now requires each menu item to be wrapped with a DOM element. The example below uses <div> elements for wrappers, but you can use any block-level element.

Old:

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

New:

1
2
3
4
5
6
7
8
 
<ul id="menu">
    <li>
        <div>One</div>
    </li>
    <li>
        <div>Two</div>
    </li>
</ul>

The autocomplete and selectmenu widgets, which both use menu internally, were both updated to include wrappers.

This is a breaking change. If you use menu directly in your project, you need to update its markup to include the wrappers. Otherwise you'll end up with a menu that looks wrong and can't be interacted with.

link Use consistent styling for focused and active items

(#10692) We used to style active parent menu items with ui-state-active, while everything else got ui-state-focus (or ui-state-hover, which we style the same as focus). When a menu item in a submenu has focus, the parent menu item gets ui-state-active, which is inconsistent and confusing. We've now switched to using only the ui-state-active class.

link Resizable

link Deprecated distance and delay options

See the notes for the mouse widget.

link Selectable

link Deprecated distance and delay options

See the notes for the mouse widget.

link Selectmenu

link Require wrappers for each selectmenu item

See the changes in the menu widget.

link Added _renderButtonItem() method

(#10142) The new extension method ._renderButtonItem() makes customizations of how the selected item is rendered a lot easier.

link Support width: false and default to 14em

(#11198) width: null still matches the width of the original element. width: false prevents an inline style from being set for the width. This makes it easy to set the width via a stylesheet and allows the use of any unit for setting the width, such as the new default of 14em, which is set through the stylesheet.

link Uses button.css

Instead of duplicating CSS, the selectmenu widget now reuses classes defined in button.css. If you're building jQuery UI manually, you need to include button.css as a dependency for selectmenu.

link Slider

link Added handleIndex to start, slide, stop, and change events

(#7630) Sliders now provide the index of the handle that's being moved inside the start, slide, stop, and change events. The index is provided in the handleIndex property of the ui parameter.

1
2
3
4
5
6
 
$( "#slider" ).slider( {
    values: [ 10, 20 ],
    slide: function( event, ui ) {
        console.log( "Handle " + ui.handleIndex + " moved to " + ui.value );
    }
} );

link Sortable

link Deprecated distance and delay options

See the notes for the mouse widget.

link Spinner

link Deprecated _buttonHtml() and _uiSpinnerHtml() extension methods

(#11097) The _buttonHtml() and _uiSpinnerHtml() methods which were used to customize the markup generated for the spinner have been considerably simplified over time. At this point, the markup used is so minimal that we no longer feel it's necessary to include these extension points. As a result, these have been deprecated. Custom styling can still be accomplished via the classes option.

link Tabs

link Deprecated ui-tab class, replaced with ui-tabs-tab

(#12061) The tabs widget now adds the ui-tabs-tab class instead of the inconsistently named ui-tab to each tab element.

link Tooltip

link Deprecated tooltipClass in favor of classes.ui-tooltip

(#12167) The tooltipClass option is now deprecated. Use the new classes option with the ui-tooltip property instead.

Old:

1
2
3
 
$( ".content" ).tooltip( {
    tooltipClass: "warning"
} );

New:

1
2
3
4
5
 
$( ".content" ).tooltip( {
    classes: {
        "ui-tooltip": "warning"
    }
} );

link Allow DOM elements and jQuery objects as content

(#9278) Tooltip now accepts HTMLElement and jQuery objects for the content option.

link Widget

(#7053) jQuery UI used to hardcode classes like ui-corner-all in widgets. We removed the hardcoding and added the ability to customize the style-related classes based on the functional classes. For the dialog, droppable and tooltip widgets, we replaced options that were doing just that.

Here's an example using dialog:

1
2
3
4
5
6
 
$( "#dialog" ).dialog( {
    classes: {
        "ui-dialog": "ui-corner-top awesome-fade-class",
        "ui-dialog-titlebar": null
    }
} );

This will add the ui-corner-top and awesome-fade-class classes to the element which has the ui-dialog class, while also removing the default ui-corner-all class from the element which has the ui-dialog-titlebar class.

link Added support for widget mixins

(#12601) The widget factory now supports mixins so that you can have common behaviors shared across many widgets in scenarios where inheritance doesn't make sense. Until now, this required manually extending the widget prototype with the mixins. Under the hood, this is all that's happening, but there's now dedicated syntax to make calls to the widget factory a little cleaner.

Old:

1
2
3
4
 
$.widget( "demo.widget", $.extend( {}, someMixin, someOtherMixin, {
 
    // Widget prototype
} );

New:

1
2
3
4
 
$.widget( "demo.widget", [ someMixin, someOtherMixin, {
 
    // Widget prototype
} ] );

link Added form reset mixin

(#12638) A form reset mixin has been added to simplify the logic of refreshing form elements when their associated form is reset. For full details see the form reset mixin documentation.

link Effects

link Converted transfer effect to a jQuery plugin method

(#14749) The transfer effect was available through the extended .show(), .hide() and .toggle() methods, which was a side-effect of exposing it as an effect, but made no semantic sense. The effect is now available exclusively through the .transfer() method.

Old:

1
2
3
 
$( ".from" ).effect( "transfer", {
    to: $( ".target" )
} );

New:

1
2
3
 
$( ".from" ).transfer( {
    to: $( ".target" )
} );

link Added .cssClip()

The new .cssClip() method is a convenience method for getting and setting the CSS clip property as an object. The object contains top, right, bottom, and left properties. For example, if you want to clip off 10 pixels from the right side of an element:

1
2
3
4
 
var element = $( ".elem" );
var clip = element.cssClip();
clip.right -= 10;
element.cssClip( clip );

link Added low-level effects APIs

A number of new low-level effects APIs have been created to aid in the development of custom effects.

link Theme

link Removed ui-icon-carat-* classes; renamed to ui-icon-caret-*

(#15022) The caret icons all had a typo in their names, which has now been fixed.