How to Use jQuery UI _setOption Method

This article explains how to handle dynamic widget configuration changes using the jQuery UI _setOption() method. When building custom plugins with the jQuery UI Widget Factory, widgets frequently need to update their internal state or modify the DOM when an option is altered after initialization. Overriding _setOption() provides a centralized, standard way to intercept option changes, execute appropriate side effects, and maintain synchronization between widget settings and the user interface.

Understanding the Role of _setOption()

In jQuery UI, options are initially set during initialization via _create(). However, users can update options later by calling $(selector).myWidget("option", "property", value).

Behind the scenes, this call invokes the internal _setOption( key, value ) method for each key-value pair being updated. By default, the base widget implementation simply stores the new value in this.options. To execute specific actions when a property changes—such as updating element styles, re-rendering templates, or toggling event listeners—you must override this method in your custom widget definition.

Basic Syntax and the Call to _super()

When overriding _setOption(), it is critical to call this._super( key, value ). This ensures that the widget's internal this.options object is properly updated with the incoming value.

$.widget("custom.myWidget", {
    options: {
        color: "blue",
        disabled: false
    },

    _create: function() {
        this.element.css("background-color", this.options.color);
    },

    _setOption: function(key, value) {
        this._super(key, value);

        if (key === "color") {
            this.element.css("background-color", value);
        }
    }
});

Calling this._super( key, value ) first allows the option value to be applied internally. However, if your logic requires access to the previous value before it gets overwritten, you can inspect this.options[key] before executing this._super().

Handling Multiple Keys with a switch Statement

As widgets grow in complexity, managing multiple dynamic options using if/else ladders can become difficult to maintain. Using a switch statement provides clean and organized handling for each supported configuration key.

$.widget("custom.advancedBox", {
    options: {
        title: "Default Title",
        width: 200,
        theme: "light"
    },

    _create: function() {
        this._render();
    },

    _setOption: function(key, value) {
        this._super(key, value);

        switch (key) {
            case "title":
                this.element.find(".widget-title").text(value);
                break;
            case "width":
                this.element.width(value);
                break;
            case "theme":
                this.element
                    .removeClass("theme-light theme-dark")
                    .addClass("theme-" + value);
                break;
        }
    }
});

Handling Batch Updates with _setOptions()

When users pass an entire object of settings via $(selector).myWidget("option", { ... }), the widget factory calls _setOptions(), which iterates over the key-value pairs and invokes _setOption() individually for each property.

If multiple option updates require an expensive DOM redraw, handling them individually inside _setOption() can degrade performance. In such cases, you can override _setOptions() to set a flag or delay rendering until all options have been processed:

_setOptions: function(options) {
    this._super(options);
    this._refresh(); // Run an expensive redraw once after all options are processed
}

By leveraging _setOption() for immediate individual updates and coordinating batch updates through _setOptions(), custom jQuery UI widgets remain responsive, organized, and compliant with standard Widget Factory conventions.