Widget Factory

You can create new widgets from scratch, using just the $.Widget object as a base to inherit from, or you can explicitly inherit from existing jQuery UI or third-party widgets. Defining a widget with the same name as you inherit from even allows you to extend widgets in place.

jQuery UI contains many widgets that maintain state and therefore have a slightly different usage pattern than typical jQuery plugins. All of jQuery UI's widgets use the same patterns, which is defined by the widget factory. So if you learn how to use one widget, then you'll know how to use all of them.

Note: This documentation shows examples using the progressbar widget but the syntax is the same for every widget.

Initialization

In order to track the state of the widget, we must introduce a full life cycle for the widget. The life cycle starts when the widget is initalized. To initialize a widget, we simply call the plugin on one or more elements.

$( "#elem" ).progressbar();

This will initialize each element in the jQuery object, in this case the element with an id of "elem". Because we called the progressbar() method with no parameters, the widget is initialized with its default options. We can pass a set of options during initialization in order to override the default options.

$( "#elem" ).progressbar({ value: 20 });

We can pass as many or as few options as we want during initialization. Any options that we don't pass will just use their default values.

The options are part of the widget's state, so we can set options after initialization as well. We'll see this later with the option method.

Methods

Now that the widget is initialized, we can query its state or perform actions on the widget. All actions after initialization take the form of a method call. To call a method on a widget, we pass the name of the method to the jQuery plugin. For example, to call the value() method on our progressbar widget, we would use:

$( "#elem" ).progressbar( "value" );

If the method accepts parameters, we can pass them after the method name. For example, to pass the parameter 40 to the value() method, we can use:

$( "#elem" ).progressbar( "value", 40 );

Just like other methods in jQuery, most widget methods return the jQuery object for chaining.

$( "#elem" )
  .progressbar( "value", 90 )
  .addClass( "almost-done" );

Each widget will have its own set of methods based on the functionality that the widget provides. However, there are a few methods that exist on all widgets, which are documented below.

Events

All widgets have events associated with their various behaviors to notify you when the state is changing. For most widgets, when the events are triggered, the names are prefixed with the widget name. For example, we can bind to progressbar's change event which is triggered whenever the value changes.

$( "#elem" ).bind( "progressbarchange", function() {
  alert( "The value has changed!" );
});

Each event has a corresponding callback, which is exposed as an option. We can hook into progressbar's change callback instead of binding to the progressbarchange event, if we want to.

$( "#elem" ).progressbar({
  change: function() {
    alert( "The value has changed!" );
  }
});

All widgets have a create event which is triggered upon instantiation.