Create a custom jQuery plug-in
Extend the jQuery library with your own reusable code
The jQuery library is designed to speed up JavaScript development. It helps you write less code by simplifying the way you write JavaScript. When using the jQuery library, you might find that you rewrite the same code for common functions. If this is the case, this may be a reason for you to write your own custom jQuery plug-in.
jQuery plug-ins let you extend the jQuery library with custom code; you can use plug-ins for any repetitive function. For example, many plug-ins are available for slideshows and for drop-down and accordion menus. If you search for jQuery plug-ins, you'll find plenty of examples that you can use in your own projects (and see how they were built).
In this article, learn how to quickly create a custom jQuery plug-in. Example code and step-by-step instructions show you how to create a jQuery accordion plug-in. If you know jQuery and are ready to take your skills to the next level, this article is perfect for you.
You can download the source code for the examples used in this article.
Prerequisites
This article assumes you have a basic understanding of JavaScript, jQuery, and cascading style sheets. See Related topics to learn more about these prerequisites.
Getting started
jQuery is a library that extends the JavaScript language. When creating a jQuery
plug-in, you're essentially extending the jQuery library, which in turn is extending
JavaScript itself. Truly understanding how your plug-in extends the jQuery library
requires an understanding of the JavaScript prototype
property. Although it is not used directly, the JavaScript prototype
property is used behind the scenes through the jQuery property fn
, which is a jQuery alias for the native JavaScript
prototype
property.
To create a new jQuery plug-in
using the fn
property, simply assign a plug-in name
to the fn
property and point it to a new function that
will act as the constructor function, similar to plain JavaScript. The code in
Listing 1 shows how to define a new jQuery plug-in named
accordion
by using the jQuery
object and the
fn
property and assigning it to a new constructor function.
Listing 1. Defining a new jQuery plug-in named accordion
jQuery.fn.accordion = function() { // Add plugin code here };
Listing 1 shows one way to create a jQuery plug-in; there is
nothing functionally wrong with the example. However, the recommended
way to create a jQuery plug-in is to first create a wrapper function that lets you
use the dollar sign ($
). By default, the dollar sign can
cause conflicts with other JavaScript frameworks. If you wrap your plug-in
in a function, conflicts won't occur with other JavaScript frameworks and the use of
the dollar sign. The example code in Listing 2 shows how to
apply a wrapper function to a jQuery plug-in definition.
Listing 2. Wrapping a new jQuery plug-in named accordion in a wrapper function
(function($) { $.fn.accordion = function() { // Add plugin code here }; })(jQuery);
In Listing 2 the jQuery
keyword is applied to the
wrapper function, which lets you use the dollar sign within the plug-in as you
do when using the fn
property. With the
wrapper function in place, you can use the dollar sign in lieu of the
jQuery
keyword anywhere throughout the plug-in
without interfering with other third-party plug-ins. This option provides a way to
write less code throughout the plug-in and helps to keep your plug-in code cleaner and easier
to maintain.
Maintaining chainability
A benefit of jQuery is that it lets you use any type of selector.
However, you must keep in mind that your plug-in can be dealing
with several different element types. Using the this
keyword lets your plug-in apply the associated functions by accessing each
element in a loop regardless of the element type. If you use the return
keyword in front of the each
loop, you can maintain
chainability with your plug-in. Listing 3
shows the each
loop being assigned to a function handler
and combined with the return
keyword.
Listing 3. Using the return
keyword
in front of the each
loop
(function($) { $.fn.accordion = function() { return this.each(function() { // Using return allows for chainability }); }; })(jQuery);
With the code in Listing 3, the example accordion plug-in can be used in a chain of method calls. With chainability—another great jQuery feature—your plug-in can be used in a chain of method calls. For example, the following code shows how an HTML element is faded out and then removed from the document object model (DOM) in a single chain of method calls.
$("#my-div").fadeOut().remove();
Structuring an accordion
A typical accordion design includes title bars and related content areas. Definition lists
are a great HTML structure for accordions; dt
elements are used for titles and dd
elements are used for
content areas. The HTML structure in Listing 4 is a definition list with four titles and their corresponding content areas.
Listing 4. A single chain of method calls
<dl class="accordion" id="my-accordion"> <dt>Section 1</dt> <dd>Mauris mauris ante, blandit et, ultrices a, suscipit eget, quam.</dd> <dt>Section 2</dt> <dd>Vestibulum a velit eu ante scelerisque vulputate.</dd> <dt>Section 3</dt> <dd>Nam mi. Proin viverra leo ut odio. Curabitur malesuada.</dd> <dt>Section 4</dt> <dd>Vivamus nisi metus, molestie vel, gravida in, condimentum sit amet, nunc.</dd> </dl>
The definition list in Listing 4 also has a CSS class named accordion
assigned to it. Without any CSS applied, this accordion structure looks similar to
the bare-bones design in Figure 1.
Figure 1. Accordion structure without any CSS applied

The accordion
class is used to apply styles to the
overall definition list, the titles, and the content areas. In the example in Listing 5,
the accordion
class itself applies a width, border, font
family, and font size. You can modify any of the proceeding CSS examples to include
your own custom styles, such as color, font family, sizes, and spacing.
Listing 5. Accordion CSS class used to define styles for the overall definition list
.accordion { width: 500px; border: 1px solid #ccc; border-bottom: none; font-family: Arial, Helvetica, sans-serif; font-size: 12px; }
You then use the accordion
CSS class to define the
styles for the titles (dt
) and content
(dd
). The titles and content both include shared
styles that define a bottom border and set the margin to 0, which allows the title
bars and content areas to rest snuggly against each other, as in
Listing 6.
Listing 6. Shared styles associated with titles and content areas of the accordion
.accordion dt, .accordion dd { border-bottom: 1px solid #ccc; margin: 0px; }
To make the dt
element look more like a title bar, set a
background color and add a pointer cursor so it's apparent to users that the
title bar is clickable. Various other styles are included in these classes, such as
padding, a font size, and a font weight. The dd
element has added padding to space out the description a bit from the titles.
Listing 7 shows an example.
Listing 7. CSS classes associated with title and content areas of the accordion
.accordion dt { background: #eaeaea; cursor: pointer; padding: 8px 4px; font-size: 13px; font-weight: bold; } .accordion dd { padding: 12px 8px; }
With all of the CSS added, the visual result is more complete and accordion-like, as in Figure 2.
Figure 2. An accordion structure with custom CSS applied

Custom coding your plug-in
To make a functional accordion, you must apply custom code to the jQuery plug-in function that you started creating in the previous section. The accordion plug-in starts by looping through all defined accordions. To define an accordion, use the following jQuery within the HTML document or within an externally embedded JavaScript file.
$('dl#my-accordion').accordion();
For each accordion, you access the associated definition titles using jQuery's
children
method, which returns an array or
dt
elements. Apply a click
event to the dt
elements, then apply a method
named reset
to each dt
.
The reset
method collapses all dd
elements when the accordion first loads. The click
event triggers a custom method named onClick
when a
dt
element or title bar is clicked. The custom
onClick
method looks for all the
dt
elements within the accordion. It calls a custom
hide
method, which hides every associated
dd
element by using the next
method to find the dd
element next to the
dt
element, and then slides it up to animate it closed.
After all dd
elements are hidden, the
dd
element associated with the clicked
dt
element becomes visible using the
slideDown
method and creates an expanding and contracting
animation, as in Listing 8. The final line of code in the
onClick
method is return false
,
which ensures that any title bar that is clicked does not exhibit its usual behavior.
For example, if you used an anchor
element as the title
bar, you would want to return false
so the user isn't
directed to another page or portion of the existing page.
Listing 8. Custom accordion functions used to create a jQuery plug-in
(function($) { $.fn.accordion = function(options) { return this.each(function() { var dts = $(this).children('dt'); dts.click(onClick); dts.each(reset); }); function onClick() { $(this).siblings('dt').each(hide); $(this).next().slideDown('fast'); return false; } function hide() { $(this).next().slideUp('fast'); } function reset() { $(this).next().hide(); } } })(jQuery);
When this accordion plug-in is associated with an HTML definition list structure like
the one you previously created, the accordion function will be applied. With
accordion functions, when one title bar or dt
element is clicked, its content area is opened and any other open content areas are
closed. In other words, only one content area can be open at a time.
Defaults and options
A jQuery plug-in can include defaults and options. Options are essentially
arguments that you can pass to your plug-in. Rather than
sending several arguments, with options you can send one argument as an object
literal,
which is a standard jQuery practice. When allowing options in your plug-in, it is a
best practice to set default options using the defaults
object. Like options, defaults are an object literal that should include
the properties you are allowing to be passed to your plug-in.
For example, if you're allowing a property that can be used to open the first content area of the
accordion when it is first loaded, you should include a default for the open
property within your plug-in. Use defaults within your plug-in to determine default
functions and use options to override default values. When the plug-in
receives the options, you can use the $.extend
method
to do the actual overriding. jQuery's $.extend
method
merges two or more objects. The example in Listing 9 shows the common practice of using the $.extend
method to merge user-defined options with the default options in a custom jQuery
plug-in.
Listing 9. Adding options and defaults to a custom accordion jQuery plug-in
(function($) { $.fn.accordion = function(options) { var settings = $.extend({}, {open: false}, options); return this.each(function() { var dts = $(this).children('dt'); dts.click(onClick); dts.each(reset); if(settings.open) $(this).children('dt:first-child').next().show(); }); function onClick() { $(this).siblings('dt').each(hide); $(this).next().slideDown('fast'); return false; } function hide() { $(this).next().slideUp('fast'); } function reset() { $(this).next().hide(); } } })(jQuery);
The $.extend
method arguments are a target object and
two or more objects to merge. In the example, the target object is an empty object
literal that acts as the container for the merged objects. The target
will become a single object that includes the values of the merged objects—in
this case, the settings
variable. The second argument is
an object literal that includes the default plug-in properties. The third argument
is the user-defined options argument. To pass options using the accordion plug-in on
an HTML element, you need to know which properties the plug-in excepts before
you can pass them as an object literal, as shown below.
$('dl#my-accordion').accordion({open:true});
In the example in Listing 9, the options that are passed to the plug-in override the defaults
through the $.extend
method. If no options are
passed, the default values are used. For the example plug-in, you use the
open
property to determine whether the first content
area should be open when it loads.
Reusability
You can reuse the example accordion plug-in in any HTML document, and can use it multiple times in a single HTML document. You can include multiple accordion structures, like the one already created, and define each separately as an accordion with jQuery using the new accordion plug-in you created. To add multiple accordions to an HTML document, simply add as many accordion structures as you desire. The code in Listing 10 includes two accordion structures separated by a paragraph.
Listing 10. Using multiple accordions within the same HTML document
<dl class="accordion" id="my-accordion"> <dt>Section 1</dt> <dd>Mauris mauris ante, blandit et, ultrices a, suscipit eget, quam.</dd> <dt>Section 2</dt> <dd>Vestibulum a velit eu ante scelerisque vulputate.</dd> <dt>Section 3</dt> <dd>Nam mi. Proin viverra leo ut odio. Curabitur malesuada.</dd> <dt>Section 4</dt> <dd>Vivamus nisi metus, molestie vel, gravida in, condimentum sit amet, nunc.</dd> </dl> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p> <dl class="accordion" id="my-accordion2"> <dt>Section 1</dt> <dd>Mauris mauris ante, blandit et, ultrices a, suscipit eget, quam.</dd> <dt>Section 2</dt> <dd>Vestibulum a velit eu ante scelerisque vulputate.</dd> </dl>
The two accordion structures in Listing 10 are nearly identical, aside from their content and,
more importantly, their ID values. The first structure includes an ID value of
my-accordion
. The second structure includes an ID
value of my-accordion2
. These structures can now be targeted independently
from one another. For example, the following jQuery script defines each accordion
structure as an accordion using the new plug-in you've created.
$('dl#my-accordion').accordion({open:true}); $('dl#my-accordion2').accordion({open:true});
Both accordion structures are defined, with the first panel set to open by default. Figure 3 shows an example of multiple accordion plug-ins being used in the same HTML document.
Figure 3. Multiple accordion structures used in the same HTML document

Putting it together
After you have created the new custom jQuery accordion plug-in, written the CSS, and
put the HTML markup in place, you can put it all together into a final web page.
To get the jQuery accordion plug-in working, you must embed the jQuery library. I
prefer to use the content delivery network (CDN), which delivers the library based on
the geographic location of the user and in turn delivers the file in the fastest way
possible. Google includes the jQuery library on its CDN, and you can embed the file in
your web pages using the URL https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js
.
Other versions of the library are also available. See Related topics for a link to the libraries on Google's developer website. The only other files that you need to reference in your HTML document are the CSS file that styles the accordion and the jQuery accordion plug-in. After that, the HTML markup for the actual accordion structures will be transformed. Listing 11 shows an example.
Listing 11. Defining two accordion structures as jQuery accordions
<!DOCTYPE HTML> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <title>Creating a Custom jQuery Plugin</title> <link type="text/css" rel="stylesheet" href="jquery.accordion.css" /> <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"> </script> <script type="text/javascript" src="jquery.accordion.js"></script> <script type="text/javascript"> $(document).ready(function() { $('dl#my-accordion').accordion({open:true}); $('dl#my-accordion2').accordion({open:true}); }); </script> </head> <body> <dl class="accordion" id="my-accordion"> <dt>Section 1</dt> <dd>Mauris mauris ante, blandit et, ultrices a, suscipit eget, quam.</dd> <dt>Section 2</dt> <dd>Vestibulum a velit eu ante scelerisque vulputate.</dd> <dt>Section 3</dt> <dd>Nam mi. Proin viverra leo ut odio. Curabitur malesuada.</dd> <dt>Section 4</dt> <dd>Vivamus nisi metus, molestie vel, gravida in, condimentum sit amet, nunc.</dd> </dl> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p> <dl class="accordion" id="my-accordion2"> <dt>Section 1</dt> <dd>Mauris mauris ante, blandit et, ultrices a, suscipit eget, quam.</dd> <dt>Section 2</dt> <dd>Vestibulum a velit eu ante scelerisque vulputate.</dd> </dl> </body> </html>
Conclusion
In this article, you learned that it is fairly easy to create a custom jQuery plug-in. Any repetitive functions that you create can quickly be converted into a plug-in to speed up your development and increase efficiency. Reusability is the key to any plug-in, and reusability equals increased productivity.
Downloadable resources
- PDF of this content
- Create and run a custom jQuery accordion plugin (custom-jquery-plugin.zip | 3KB)
Related topics
- "JavaScript and the Document Object Model" (developerWorks, July 2002): This article explores the JavaScript approach to DOM and chronicles the building of a web page to which the user can add notes and edit note content.
- "Get started with the JavaScript language, Part 1: JavaScript language fundamentals" (developerWorks, April 2011): Read this article to learn basic JavaScript concepts.
- "Understanding built-in objects in JavaScript" (developerWorks, August 2011): Gain a foundational understanding of the intrinsic objects available in the JavaScript language.
- "Achieve cross-browser functionality with HTML5 and CSS3" (developerWorks, February 2011): Learn new techniques to use on the latest browsers.
- jQuery library on IBM developerWorks: Explore articles, blogs, and forums.
- Google Libraries API - Developer's Guide: Get a CDN version of the jQuery library.
- developerWorks Web development zone: Find articles covering various web-based solutions. See the Web development technical library for a wide range of technical articles and tips, tutorials, standards, and IBM Redbooks.
- IBM product evaluation versions: Download or explore the online trials in the IBM SOA Sandbox and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.