10 Tips for Developing Better jQuery Plugins

There are some great jQuery plugins. The better ones are adopted by thousands of web developers throughout the world. Unfortunately, the worse ones fail and disappear into obscurity. Here are some tips to ensure your plugins reach their full potential…

1. Don’t Break the Chain

Unless your plugin returns a value, the last line of your plugin function must be:


return this;

this ensures method calls can be chained, e.g.


$("div#myid").yourPlugin().anotherPlugin().yetAnotherPlugin();

2. Make it Easy to Use

In most cases, your plugin should simply work without the developer having to wade though documentation, set options or edit your plugin code.

If it’s a visual widget, the developer shouldn’t need to edit any JavaScript. You can simply provide HTML with a class/ID which will automatically launch your code, e.g.


<section class="myjqWidget">
<p>My content</p>
</section>

Your plugin can initialize itself, e.g.


$(function() {
		$("section.myjqWidget").myjqWidget();
});

3. Use Suitable Naming and Version Control Numbers

There are a lot of jQuery plugins. If you’re considering the name “tab” for your tab-handling plugin, there’s a strong possibility it’s been used already. That may not always matter but avoid using names which are ambiguous or likely to clash.

Version numbering is also useful. It’s becomes especially important when developers report problems.

4. Use a Closure

Never depend on ‘$’ referencing jQuery. If the developer has another library installed, it may have grabbed it before jQuery was loaded. The simplest way to solve the issue is to pass jQuery as the ‘$’ argument for an anonymous self-starting function, e.g.


(function($) {
	// code here can use $ to reference jQuery
})(jQuery);

5. Set Default Parameters

Most plugins set parameters using JavaScript object literal notation, e.g.


$("#select").MyPlugin({opt1: 1, opt2: 2, opt3: "three"});

This has several advantages: parameters are easy to read, can be ordered in any way and omitted completely. However, you should set defaults within your plugin code and override them accordingly, e.g.


$.fn.PlugIn = function(opts) {
	// default configuration
	var config = $.extend({}, {
		opt1: 1,
		opt2: 2,
		opt3: 3,
		opt4: 4,
		opt5: 5
	}, opts);

Your plugin can then reference parameters using code such as config.opt1.

6. Support HTML Parameters

Ideally, HTML widgets should be able to set parameters without the developer needing to change JavaScript code. You could consider HTML5 data attributes, e.g.


<section class="myjqWidget" data-opt1="1" data-opt2="two">
<p>My content</p>
</section>

These can be accessed via jQuery’s data method: .data("opt1").

7. Document Your Code

Add concise comments to the top of your plugin which describe:

  • the plugin name and version
  • what the plugin does
  • example uses
  • the parameters
  • contact and support links

If it’s particularly complex, consider a separate readme file.

8. Test Your Plugin Thoroughly

Test it. Then test it again. In all browsers.

There may be issues you’re not prepared to fix, e.g. IE6 compatibility problems. That’s fine, but ensure it’s mentioned within your documentation.

9. Use a Good Template

Here’s the template code I use when creating a new plugin:


/*!
 * jQuery plugin
 * What does it do
 */
(function($) {

	$.fn.PlugInName = function(opts) {
	
		// default configuration
		var config = $.extend({}, {
			opt1: null
		}, opts);
	
		// main function
		function DoSomething(e) {
		}

		// initialize every element
		this.each(function() {
			DoSomething($(this));
		});

		return this;
	};

	// start
	$(function() {
		$("#select").PlugInName();
	});

})(jQuery);

It provides a good starting point:

  • The plugin is wrapped in an enclosure.
  • It sets default options which are overridden by plugin parameters.
  • Each selected element is passed to the DoSomething function as a jQuery object.
  • return this; is included.
  • Auto-start code is provided at the end.

10. Get The Word Out

If you want developers to use your plugin, upload it to repositories such as GitHub, Google Code and jQuery Plugin directories. Create demonstration pages, publicize it in articles and tweet about it incessantly.

Then be prepared to support the plugin and update it when necessary. You will receive dumb questions and bizarre feature requests, but that’s all part of being a successful plugin author.

Do you have any top-tips for effective jQuery plugin development?

Free book: Jump Start HTML5 Basics

Grab a free copy of one our latest ebooks! Packed with hints and tips on HTML5's most powerful new features.

  • http://www.carolinamantis.com Tony Miller

    I came across this one:

    http://www.websanova.com/tutorials/jquery/jquery-plugin-development-boilerplate

    One difference is that that author (not me) returns this.each, whereas you return this. What differences in semantics does that make?

    • http://www.optimalworks.net/ Craig Buckler

      I don’t think it’s different. ‘this’ is still returned but, before that happens, the each method will execute.

  • http://about.me/johnkpaul John K Paul

    Top Tip #1, for me, is unit testing. This is especially true for plugins that are intended to be distributed and widely used. I actually just gave a talk about how to unit test jQuery plugins that can be found here – http://vimeo.com/39112165

  • http://bdelespierre.fr Ben

    I disagree with the “auto-start” thing, I think it’s best for the application developper to choose whenever or not to activate the plugin, but I agree this taks sould be as easy for him as possible.

    • http://www.optimalworks.net/ Craig Buckler

      Why? It would just be a matter of assigning an appropriate ID or class to an element so the plug-in code automatically runs without you needing to do that in JavaScript. If you don’t want auto-starting, you wouldn’t use that ID/class and write the start-up code yourself.

  • http://joezimjs.com Joseph

    It seems everyone is doing a post on this lately:
    5 Tips to Make Your jQuery Plugins Awesome
    10 Coding Tips to Write Superior jQuery Plugins
    jQuery Plugin Development Tips
    10 Tips for Writing Awesome jQuery Plugins

    It sounds like we need to come up with something new to talk about. Something that is worth reading and not just designed to suck traffic in. By no means am I innocent in this matter either, but I guess traffic is all we’re really after.

  • Jonathan Worent

    I believe visual widgets should be able to build themselves as you say… However I better also be able to control every aspect of that markup. I think YUI’s widgets are exemplary in this regard. I’d like to see more jQuery widgets do this. I generally prefer to progressively enhance existing markup. This also help keep the FOUC (Flash Of Unstyled Content) down.