Home Original page

Widget Factory | jQuery UI API Documentation

Description: The base widget used by the widget factory.

QuickNav

Options

Methods

Events

Options

classes 

Default: {}

Additional (thematic) classes to add to the widget, in addition to the structural classes. The structural classes are used as keys of this option and the thematic classes are the values. See the _addClass() method for using this in custom widgets. Check out the documentation of individual widgets to see which classes they support.

The primary motivation of this option is to map structural classes to theme classes. In other words, any class prefixed with namespace and widget, like "ui-progressbar-", is considered a structural class. These are always added to the widget. In contrast to that, any class not specific to the widget is considered a theme class. These could be part of jQuery UI's CSS framework, but can also come from other CSS frameworks or be defined in custom stylesheets.

Setting the classes option after creation will override all default properties. To only change specific values, use deep setters, e.g. .option( "classes.ui-progressbar-value", null ).

Code examples:

Initialize a progressbar widget with the classes option specified, changing the theming for the ui-progressbar class:

1

2

3

4

5

 
$( ".selector" ).progressbar({
    "ui-progressbar": "highlight"

Get or set the classes option, after initialization:

1

2

3

4

5

6

7

8

 
var classes = $( ".selector" ).widget( "option", "classes" );
// Setter, override all classes
$( ".selector" ).widget( "option", "classes", { "custom-header": "icon-warning" } );
// Setter, override just one class
$( ".selector" ).widget( "option", "classes.custom-header", "icon-warning" );

disabled 

Default: false

Disables the widget if set to true.

Code examples:

Initialize the widget with the disabled option specified:

1

2

3

 
$( ".selector" ).widget({

Get or set the disabled option, after initialization:

1

2

3

4

5

 
var disabled = $( ".selector" ).widget( "option", "disabled" );
$( ".selector" ).widget( "option", "disabled", true );

hide 

Default: null

If and how to animate the hiding of the element.

Multiple types supported:

  • Boolean: When set to false, no animation will be used and the element will be hidden immediately. When set to true, the element will fade out with the default duration and the default easing.
  • Number: The element will fade out with the specified duration and the default easing.
  • String: The element will be hidden using the specified effect. The value can either be the name of a built-in jQuery animation method, such as "slideUp", or the name of a jQuery UI effect, such as "fold". In either case the effect will be used with the default duration and the default easing.
  • Object: If the value is an object, then effect, delay, duration, and easing properties may be provided. If the effect property contains the name of a jQuery method, then that method will be used; otherwise it is assumed to be the name of a jQuery UI effect. When using a jQuery UI effect that supports additional settings, you may include those settings in the object and they will be passed to the effect. If duration or easing is omitted, then the default values will be used. If effect is omitted, then "fadeOut" will be used. If delay is omitted, then no delay is used.

Code examples:

Initialize the widget with the hide option specified:

1

2

3

 
$( ".selector" ).widget({
  hide: { effect: "explode", duration: 1000 }

Get or set the hide option, after initialization:

1

2

3

4

5

 
var hide = $( ".selector" ).widget( "option", "hide" );
$( ".selector" ).widget( "option", "hide", { effect: "explode", duration: 1000 } );

show 

Default: null

If and how to animate the showing of the element.

Multiple types supported:

  • Boolean: When set to false, no animation will be used and the element will be shown immediately. When set to true, the element will fade in with the default duration and the default easing.
  • Number: The element will fade in with the specified duration and the default easing.
  • String: The element will be shown using the specified effect. The value can either be the name of a built-in jQuery animation method, such as "slideDown", or the name of a jQuery UI effect, such as "fold". In either case the effect will be used with the default duration and the default easing.
  • Object: If the value is an object, then effect, delay, duration, and easing properties may be provided. If the effect property contains the name of a jQuery method, then that method will be used; otherwise it is assumed to be the name of a jQuery UI effect. When using a jQuery UI effect that supports additional settings, you may include those settings in the object and they will be passed to the effect. If duration or easing is omitted, then the default values will be used. If effect is omitted, then "fadeIn" will be used. If delay is omitted, then no delay is used.

Code examples:

Initialize the widget with the show option specified:

1

2

3

 
$( ".selector" ).widget({
  show: { effect: "blind", duration: 800 }

Get or set the show option, after initialization:

1

2

3

4

5

 
var show = $( ".selector" ).widget( "option", "show" );
$( ".selector" ).widget( "option", "show", { effect: "blind", duration: 800 } );

Methods

_addClass( [element ], keys [, extra ] )Returns: jQuery (plugin only)

Add classes to an element of the widget.

This provides a hook for the user to add additional classes or replace default styling classes, through the classes option.

It also provides automatic removal of these classes when a widget is destroyed, as long as you're using _addClass(), _removeClass() and _toggleClass() together. This can heavily simplify the implementation of custom _destroy() methods.

  • element

    The element to add the classes to. Defaults to this.element.

  • keys

    The classes to add, as a space-delimited list. If a property of the classes option matches a key, the value will be added as well.

    When you only need the extra argument, you can skip this argument by specifying null.

  • extra

    Additional classes to add, required for layout or other reasons. Unlike the keys argument, these aren't associated with any properties of the classes option. Just like keys, they will also be automatically removed when destroying the widget.

Code examples:

Add the ui-progressbar class to the widget's element (this.element). Will also add any additional classes specified through the classes option for the given class.

1

 
this._addClass( "ui-progressbar" );

Add the demo-popup-header class to the specified element (here referencing this.popup). Will also add any additional classes specified through the classes option for the given class. In addition, it will always add the ui-front class.

1

 
this._addClass( this.popup, "demo-popup-header", "ui-front" );

Adds the ui-helper-hidden-accessible class to the specified element. Uses null for the keys argument to skip it.

1

 
this._addClass( this.liveRegion, null, "ui-helper-hidden-accessible" );

_create()Returns: jQuery (plugin only)

The _create() method is the widget's constructor. There are no parameters, but this.element and this.options are already set.

  • This method does not accept any arguments.

Code examples:

Set the background color of the widget's element based on an option.

1

2

3

 
  this.element.css( "background-color", this.options.color );

_delay( fn [, delay ] )Returns: Number

Invokes the provided function after a specified delay. Keeps this context correct. Essentially setTimeout().

Returns the timeout ID for use with clearTimeout().

  • fn

    The function to invoke. Can also be the name of a method on the widget.

  • delay

    The number of milliseconds to wait before invoking the function. Defaults to 0.

Code examples:

Call the _foo() method on the widget after 100 milliseconds.

1

 
this._delay( this._foo, 100 );

_destroy()Returns: jQuery (plugin only)

The public destroy() method cleans up all common data, events, etc. and then delegates out to _destroy() for custom, widget-specific, cleanup.

  • This method does not accept any arguments.

Code examples:

Remove a class from the widget's element when the widget is destroyed.

1

2

3

 
  this.element.removeClass( "my-widget" );

_focusable( element )Returns: jQuery (plugin only)

Sets up element to apply the ui-state-focus class on focus.

The event handlers are automatically cleaned up on destroy.

  • element

    The element(s) to apply the focusable behavior to.

Code examples:

Apply focusable styling to a set of elements within the widget.

1

 
this._focusable( this.element.find( ".my-items" ) );

_getCreateEventData()Returns: Object

All widgets trigger the create event. By default, no data is provided in the event, but this method can return an object which will be passed as the create event's data.

  • This method does not accept any arguments.

Code examples:

Pass the widget's options to create event handlers as an argument.

1

2

3

 
_getCreateEventData: function() {

_getCreateOptions()Returns: Object

This method allows the widget to define a custom method for defining options during instantiation. The user-provided options override the options returned by this method, which override the default options.

  • This method does not accept any arguments.

Code examples:

Make the widget element's id attribute available as an option.

1

2

3

 
_getCreateOptions: function() {
  return { id: this.element.attr( "id" ) };

_hide( element, option [, callback ] )Returns: jQuery (plugin only)

Hides an element immediately, using built-in animation methods, or using custom effects. See the hide option for possible option values.

  • element

    The element(s) to hide.

  • option

    The properties defining how to hide the element.

  • callback

    Callback to invoke after the element has been fully hidden.

Code examples:

Pass along the hide option for custom animations.

1

2

3

4

5

 
this._hide( this.element, this.options.hide, function() {
  // Remove the element from the DOM when it's fully hidden.

_hoverable( element )Returns: jQuery (plugin only)

Sets up element to apply the ui-state-hover class on hover.

The event handlers are automatically cleaned up on destroy.

  • element

    The element(s) to apply the hoverable behavior to.

Code examples:

Apply hoverable styling to all <div>s within the element on hover.

1

 
this._hoverable( this.element.find( "div" ) );

_init()Returns: jQuery (plugin only)

Widgets have the concept of initialization that is distinct from creation. Any time the plugin is called with no arguments or with only an option hash, the widget is initialized; this includes when the widget is created.

Note: Initialization should only be handled if there is a logical action to perform on successive calls to the widget with no arguments.

  • This method does not accept any arguments.

Code examples:

Call the open() method if the autoOpen option is set.

1

2

3

4

5

 
  if ( this.options.autoOpen ) {

_off( element, eventName )Returns: jQuery (plugin only)

Unbinds event handlers from the specified element(s).

  • element

    The element(s) to unbind the event handlers from. Unlike the _on() method, the elements are required for _off().

  • eventName

    One or more space-separated event types.

Code examples:

Unbind all click events from the widget's element.

1

 
this._off( this.element, "click" );

_on( [suppressDisabledCheck ] [, element ], handlers )Returns: jQuery (plugin only)

Binds event handlers to the specified element(s). Delegation is supported via selectors inside the event names, e.g., "click .foo". The _on() method provides several benefits of direct event binding:

  • Maintains proper this context inside the handlers.
  • Automatically handles disabled widgets: If the widget is disabled or the event occurs on an element with the ui-state-disabled class, the event handler is not invoked. Can be overridden with the suppressDisabledCheck parameter.
  • Event handlers are automatically namespaced and cleaned up on destroy.

  • suppressDisabledCheck (default: false)

    Whether or not to bypass the disabled check.

  • element

    Which element(s) to bind the event handlers to. If no element is provided, this.element is used for non-delegated events and the widget element is used for delegated events.

  • handlers

    An object in which the keys represent the event type and optional selector for delegation, and the values represent a handler function to be called for the event.

Code examples:

Prevent the default action of all links clicked within the widget's element.

1

2

3

4

5

 
this._on( this.element, {
  "click a": function( event ) {

_removeClass( [element ], keys [, extra ] )Returns: jQuery (plugin only)

Remove classes from an element of the widget.

The arguments are the same as for the _addClass() method, the same semantics apply, just in reverse.

  • element

    The element to remove the classes from. Defaults to this.element.

  • keys

    The classes to remove, as a space-delimited list. If a property of the classes option matches a key, the value will be removed as well.

    When you only need the extra argument, you can skip this argument by specifying null.

  • extra

    Additional classes to remove, required for layout or other reasons. Unlike the keys argument, these aren't associated with any properties of the classes option.

Code examples:

Remove the ui-progressbar class from the widget's element (this.element). Will also remove any additional classes specified through the classes option for the given class.

1

 
this._removeClass( "ui-progressbar" );

Remove the demo-popup-header class from the specified element (here referencing this.popup). Will also remove any additional classes specified through the classes option for the given class. In addition, it will also remove the ui-front class.

1

 
this._removeClass( this.popup, "demo-popup-header", "ui-front" );

Remove the ui-helper-hidden-accessible class from the specified element. Uses null for the keys argument to skip it.

1

 
this._removeClass( this.liveRegion, null, "ui-helper-hidden-accessible" );

_setOption( key, value )Returns: jQuery (plugin only)

Called from the _setOptions() method for each individual option. Widget state should be updated based on changes.

  • key

    The name of the option to set.

  • value

    A value to set for the option.

Code examples:

Update a widget's element when its height or width option changes.

1

2

3

4

5

6

7

8

9

 
_setOption: function( key, value ) {
    this.element.width( value );
  if ( key === "height" ) {
    this.element.height( value );
  this._super( key, value );

_setOptions( options )Returns: jQuery (plugin only)

Called whenever the option() method is called, regardless of the form in which the option() method was called.

Overriding this is useful if you can defer processor-intensive changes for multiple option changes.

  • options

    An object containing options to set, with the name of the option as the key and the option value as the value.

Code examples:

Call a resize() method if the height or width options change.

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

 
_setOptions: function( options ) {
  $.each( options, function( key, value ) {
    that._setOption( key, value );
    if ( key === "height" || key === "width" ) {

_show( element, option [, callback ] )Returns: jQuery (plugin only)

Shows an element immediately, using built-in animation methods, or using custom effects. See the show option for possible option values.

  • element

    The element(s) to show.

  • option

    The properties defining how to show the element.

  • callback

    Callback to invoke after the element has been fully shown.

Code examples:

Pass along the show option for custom animations.

1

2

3

4

5

 
this._show( this.element, this.options.show, function() {
  // Focus the element when it's fully visible.

_super( [arg ] [, ... ] )Returns: jQuery (plugin only)

Invokes the method of the same name from the parent widget, with any specified arguments. Essentially .call().

  • arg

    Zero to many arguments to pass to the parent widget's method.

Code examples:

Handle title option updates and call the parent widget's _setOption() to update the internal storage of the option.

1

2

3

4

5

6

 
_setOption: function( key, value ) {
    this.element.find( "h3" ).text( value );
  this._super( key, value );

_superApply( arguments )Returns: jQuery (plugin only)

Invokes the method of the same name from the parent widget, with the array of arguments. Essentially .apply().

  • arguments

    Array of arguments to pass to the parent method.

Code examples:

Handle title option updates and call the parent widget's _setOption() to update the internal storage of the option.

1

2

3

4

5

6

 
_setOption: function( key, value ) {
    this.element.find( "h3" ).text( value );
  this._superApply( arguments );

_toggleClass( [element ], keys [, extra ], add )Returns: jQuery (plugin only)

Toggle classes of an element of the widget.

The arguments are the same as for the _addClass() and _removeClass() methods, except for the additional boolean argument that specifies to add or remove classes.

Unlike jQuery's .toggleClass() method, the boolean add argument is always required.

  • element

    The element to toogle the classes on. Defaults to this.element.

  • keys

    The classes to toogle, as a space-delimited list. If a property of the classes option matches a key, the value will be toggled as well.

    When you only need the extra argument, you can skip this argument by specifying null.

  • extra

    Additional classes to toggle, required for layout or other reasons. Unlike the keys argument, these aren't associated with any properties of the classes option. Just like keys, they will also be automatically removed when destroying the widget.

  • add

    Indicates whether to add or remove the specified classes, where a boolean true indicates that classes should be added, a boolean false indicates that classes should be removed.

Code examples:

Toggle the ui-state-disabled class on the widget's element (this.element).

1

 
this._toggleClass( null, "ui-state-disabled", !!value );

_trigger( type [, event ] [, data ] )Returns: Boolean

Triggers an event and its associated callback.

The option with the name equal to type is invoked as the callback.

The event name is the lowercase concatenation of the widget name and type.

Note: When providing data, you must provide all three parameters. If there is no event to pass along, just pass null.

If the default action is prevented, false will be returned, otherwise true. Preventing the default action happens when the handler returns false or calls event.preventDefault().

  • type

    The type should match the name of a callback option. The full event type will be generated automatically.

  • event

    The original event that caused this event to occur; useful for providing context to the listener.

  • data

    A hash of data associated with the event.

Code examples:

Trigger a search event whenever a key is pressed.

1

2

3

4

5

6

7

8

9

10

11

12

 
this._on( this.element, {
  keydown: function( event ) {
    // Pass the original event so that the custom search event has
    // useful information, such as keyCode
    this._trigger( "search", event, {
      // Pass additional information unique to this event
      value: this.element.val()

destroy()Returns: jQuery (plugin only)

Removes the widget functionality completely. This will return the element back to its pre-init state.

  • This method does not accept any arguments.

disable()Returns: jQuery (plugin only)

Disables the widget.

  • This method does not accept any arguments.

enable()Returns: jQuery (plugin only)

Enables the widget.

  • This method does not accept any arguments.

instance()Returns: Object

Retrieves the widget's instance object. If the element does not have an associated instance, undefined is returned.

Unlike other widget methods, instance() is safe to call on any element after the widget plugin has loaded.

  • This method does not accept any arguments.

option( optionName )Returns: Object

Gets the value currently associated with the specified optionName.

Note: For options that have objects as their value, you can get the value of a specific key by using dot notation. For example, "foo.bar" would get the value of the bar property on the foo option.

  • optionName

    The name of the option to get.

option()Returns: PlainObject

Gets an object containing key/value pairs representing the current widget options hash.

  • This signature does not accept any arguments.

option( optionName, value )Returns: jQuery (plugin only)

Sets the value of the widget option associated with the specified optionName.

Note: For options that have objects as their value, you can set the value of just one property by using dot notation for optionName. For example, "foo.bar" would update only the bar property of the foo option.

  • optionName

    The name of the option to set.

  • value

    A value to set for the option.

option( options )Returns: jQuery (plugin only)

Sets one or more options for the widget.

  • options

    A map of option-value pairs to set.

Events

create( event, ui )Type: widgetcreate

Triggered when the widget is created.

  • event

  • ui

Note: The ui object is empty but included for consistency with other events.

Code examples:

Initialize the widget with the create callback specified:

1

2

3

 
$( ".selector" ).widget({
  create: function( event, ui ) {}

Bind an event listener to the widgetcreate event:

1

 
$( ".selector" ).on( "widgetcreate", function( event, ui ) {} );