How to create a jQuery plugin with options

Check out the previous tutorial on how to create a simple jquery plugin.

Now let’s learn a bit jQuery plugin tutorial with some advanced skill. Let’s see how to build the same circle plugin with customizable parameters.

jQuery plugin with customization parameters

Create a div in you index page, this is our div element which animates later as a circle!.

<div id="circular" class="_default_circle"> plugin</div>

The important one is the CSS:

._default_circle{
  width:50px;
  height:50px;
  background:#00FFFF;
  border:#0000FF solid 1px; text-align:center;	    
}

._custom_circle{
  width:50px;
  height:50px;
  background:#00FFFF;
  border:#0000FF solid 5px;
  text-align:center; top:50%;
  -webkit-border-radius: 999px;
  -moz-border-radius: 999px;
  border-radius: 999px;
  behavior: url(PIE.htc);	
}

The ._default_circle is used for the div on initial load, the ._custom_circle is used when you actually access the div through your plugin.

jQuery plugin with options structure explained!

We can initiate the actual function of the plugin using the jQuery built-in structure.

(function($){....... })(jQuery);

We will use the jQuery “extend” function to have options for the plugin.

Ok, first we need to decide on how to give options to the plugin, because if you provide more options to the user, more likely is he going to like your plugin. Also, remember that complexity kills the performance, so have a balanced plugin. In this tut, I have three options included; animation speed, height, and width of the circle.

How to initialize jQuery plugin:

$.fn.extend({........ }); same way as you would initialize document ready…but, with different syntax.

Call the circle function within the extend function

circle: function() {... } , if you are passing default values then use circle: function(options) {... }

within circle function let us set our default functions like so

var defaults = {
  anim_speed : 100,
  width: 100,
  height : 100,
};

set the default values if the user does not set any in his function call.

var choice = $.extend(defaults, options);

The $.extend API will merge the contents of two or more objects together into the first object, more info jquery.extend()

So for every option, we will overwrite the default values in the plugin like this:

return this.each(function() {
  var curr = $(this);
  curr.animate({width : choice.width, height: choice.height} ,choice.anim_speed);
  curr.addClass("_custom_circle");
});

For every option, we will animate with default values or with the values the user has set.

A user will call your plugin like this  $("#circular").circle();

In this case, the default variable that you had set earlier will be used in the function.

Since you have given the options, user can call their plugin with options like this:

$("#circular").circle({
  anim_speed : 1000,
  width : 200,
  height: 200
});

Wow, congratulation! you did it…

Here is the complete code for JQuery Plugin Defaults and Options :

$(document).ready(function(){
  $("#circular").circle(
  { anim_speed : 1000, width : 200, height: 200 } 
  );
});  
(function($){
  $.fn.extend({
    circle: function(options) {
      var defaults = {
        anim_speed : 100,
        width: 100,
        height : 100,
      };
      var choice = $.extend(defaults, options);
      return this.each(function() {
        var curr = $(this);
        curr.animate({width : choice.width, height: choice.height} ,choice.anim_speed);
        curr.addClass("_custom_circle");
      });
    }
  });
})(jQuery);

Comment and let us know how you created one!