This page should be copied to docs.jquery.com/UI/API when complete to be included in our releases.

jQuery UI API

All jQuery UI plugins have a common API. This decreases the learning curve and ramp up time for learning how to use new plugins; if you've used one plugin you'll know exactly how to use every other plugin. All plugins have at least one option, but may be initialized without specifying any options.

Initialization and Options

To initialize a plugin using only the default options, you simply call it like any other jQuery method:

$('#my-elem').draggable();

To override some options on initialization, you can pass an object hash as the only parameter:

$('#my-elem').draggable({
     axis: 'x',
     containment: 'window'
});

Any options you specify in the hash will override the default values; any options you don't specify will use the default values. After you have initialized a plugin, you can change any option at any time using the option method:

$('#my-elem').plugin('option', 'axis', 'y');

You may find yourself making all, or most, instances of a certain plugin using a different value for a specific option than hte plugin's default values. Rather than having to specify the same values every time you initialize a plugin, you can change the default values that the plugin will use on initialization:

$.ui.draggable.defaults.containment = 'window';

Methods

As shown above with the option method, you can call certain methods on all plugins after initialization. In order to avoid polluting jQuery with lots of methods for each plugin, all method calls go through the same method that you use to initialize the plugin. To call a method on a plugin, you provide the name of the method as the first parameter, followed by parameters you want to pass to the method. So what would normally be method('param1', 'param2') will be plugin('method', 'param1', 'param2').

There are a few methods that are available on all plugins:

option

Gets/sets options; uses the same parameter format as .css/.attr

$('#my-elem').draggable('option', 'axis'); // getter
$('#my-elem').draggable('option', 'axis', 'y'); // setter
$('#my-elem').draggable('option', { // multi-setter
     axis: 'y',
     containment: 'window'
});

enable

Enables the plugin functionality

$('#my-elem').draggable('enable');

disable

Disables the plugin functionality

$('#my-elem').draggable('disable');

destroy

Destroys the plugin instance and reverts the element to its original state.

$('#my-elem').draggable('destroy');

Events

All UI plugins have events associated with the various ways a user can interact with the plugin. For example, draggable has start, drag and stop events. Each event has a corresponding callback exposed as an option. Every event/callback is passed two parameters: the event object and a ui hash containing information relevant to the specific action.

To specify a callback in the options, you just provide a function for the relevant option:

$('#my-elem').draggable({
     start: function(event, ui) {
          // do something with event or ui
     }
});

You can also bind to the event. You'll notice that the event name has a prefix on it, this is to prevent name collisions with native browser events:

$('#my-elem')
     .draggable()
     .bind('dragstart', function(event, ui) {
          // do something with event or ui
     });

Events are triggered before the callback is called. Calling event.preventDefault() or returning false in any of the event handlers or the callback will prevent the action from occurring. However, like native browser events, some events are not cancelable.

How to use jQuery UI widgets