Lonewolf Designs

UK based web design blog of Tim Trott

Wordpress plugins are pieces of addon code that extend the functionality of Wordpress, either behind-the-scenes or extra visual code. Widgets allow these code segments to be quickly and easily added to predefined sidebars on most themes.

Before Wordpress version 2.0, these extra visual plugins had to be hand coded into the theme template, so a knowledge of PHP is required. In version 2.0 they introduced "Widgets" which wrap around a plugin and allow a non code editing method for incorporating into a theme using sidebars and a drag and drop interface.

This tutorial covers creating a Widget, creating a plugin widget, adding sidebars to a theme, and upgrading a non-widget plugin.

Creating a Simple Wordpress Plugin

You can use this as a code snippet for your projects. I am going to create a simple plugin that does nothing but display "Hello World". I'll leave the actual functionality of the plugin to you ;)

Create a new php file in your plugin directory called my-hello-world.php, and type the following plugin code:

Plugin Name: Hello World
Plugin URI: http://lonewolf-online.net/
Description: Sample Hello World Plugin
Author: Tim Trott
Version: 1
Author URI: http://lonewolf-online.net/

function sampleHelloWorld()
  echo "<h2>Hello World</h2>";

The lines inside /* and */ are used by Wordpress to find out about the plugin. We have one function called sampleHelloWorld which does exactly that.

Now, traditionally we would have had to open up the sidebar of the theme you are using, find the location of where you want the Hello World displayed, and hard code the function in. Upload to the server and test. If for some reason there is a problem with your plugin (or a third party plugin) then your site would almost certainly stop working. Changing the location from the left to the right sidebar means editing both files accordingly. This isn't very good.


Widgets take away the need for editing the sidebar files of a theme and allow for a drag and drop interface in the admin panel. Lets have a look at how we can wiget enable our plugin.

Open up the Hello World plugin file again and add these lines:

function widget_myHelloWorld() {
  <h2 class="widgettitle">My Widget Title</h2>
  <?php sampleHelloWorld(); ?>

function myHelloWorld_init()
  register_sidebar_widget(__('Hello World'), 'widget_myHelloWorld');    
add_action("plugins_loaded", "myHelloWorld_init");

The first function here is what will be displayed on the sidebar when its set-up correctly. Notice that we are calling on our old function. This is upgrading the existing plugin to be widget enabled. You can if you like replace the function call with the function statements and combine the two functions.

The second function is called by Wordpress when the plugin is activated. It calls a Wordpress function that will register a new widget which will be called "Hello World" which will call our new widget function.

Add action just tells Wordpress to call myHelloWorld_init when the plugin is loaded.

Enhancements for Theme Compatibility

While this widget will function fine, we can make some improvements to enable greater theme compatibility – not everyone uses the same themes as you test on.

Wordpress will pass parameters to your widget, which contain information about the sidebar and the CSS classes. We should process these parameters and output the correct tags, or you risk breaking some themes.

The first thing we need to do is change our sampleHelloWorld function so that it will accept parameters, then to process these parameters into variables. This is done using the extract function.

function widget_myHelloWorld($args) {
  <h2 class="widgettitle">My Widget Title</h2>
  <?php sampleHelloWorld(); ?>

These two lines will allow us to reference some variables and output correct html structure for the theme being used. The most important variables are before_widget, after_widget, before_title and after_title. Previously we have surrounded the widget title with a hard coded H2 tag with a css class widgettitle, but many themes do not support these tags. They may use a div, or a h1 or a span, so we need our widget to be flexible.

function widget_myHelloWorld($args) {
  echo $before_widget;
  echo $before_title;?>My Widget Title<?php echo $after_title;
  echo $after_widget;

These changes will allow our plugin to use the same tags as the theme author informs us we need to use, and will allow your widget to look the same as the other widgets in the sidebar.

To configure these options inside a theme, please see the section below on theme support.

Complete Plugin:

Plugin Name: Hello World
Plugin URI: http://lonewolf-online.net/
Description: Sample Hello World Plugin
Author: Tim Trott
Version: 1
Author URI: http://lonewolf-online.net/

function sampleHelloWorld()
  echo "<h2>Hello World</h2>";

function widget_myHelloWorld($args) {
  echo $before_widget;
  echo $before_title;?>My Widget Title<?php echo $after_title;
  echo $after_widget;

function myHelloWorld_init()
  register_sidebar_widget(__('Hello World'), 'widget_myHelloWorld');    
add_action("plugins_loaded", "myHelloWorld_init");

Testing your Plugin

If you check your plugins page now, you should now have a new plugin listed called Hello World which you can activate. On the Presentation tab, select widgets, and you should see your new widget available to be dragged onto a sidebar. Save your changes and admire your new work.

Wordpress Widget listed as installed
Wordpress Widget listed as installed

Stop! My Theme Doesn't Support Widgets!

If your theme does not have widget enabled sidebars, this little tutorial will help make it widget enabled. I am using a very basic sidebar theme, most sidebars are a little more complex than this.

<div id="sidebar">
    <?php if ( !function_exists('dynamic_sidebar') || !dynamic_sidebar() ) : ?>
      <?php wp_list_pages('title_li=<h2>Pages</h2>' ); ?><br/>
          <?php wp_get_archives('type=monthly'); ?>
      <?php wp_list_categories('show_count=1&amp;title_li=<h2>Categories</h2>'); ?>
    <?php endif; ?>

The first of these lines does an if else statement, if we have a sidebar function call it otherwise we do the existing hard coded sidebar.

The second line (endif) tells the if statement where the hard coded sidebar ends. Anything between the first and second lines will be shown if widgets are disabled or no widgets are assigned to the sidebar.

Before you can add a widget to this sidebar, we need to make Wordpress aware of it by registering it.

Open, or create, functions.php in your theme folder, and find (or add) a line like this:

if ( function_exists('register_sidebars') )

Where the parameter to register_sidebars is the number of sidebars defined in your theme. You can have any number of sidebars. Now you will be able to add widgets to your sidebar.

Should you wish to configure the elements that will appear before and after a widget, or the tags that a widget title will appear in, you can setup the options array and pass it to the register_sidebar function.

'before_widget' => '<li>',
'after_widget' => '</li>',
'before_title' => '<div class="sidebar_title">',
'after_title' => '</div>',

This will cause the widget to be contained within &lt>&lt/li> tags and the widget title will be in a div with the css class sidebar_title.

As with most programming and development, there are a number of different methods of obtaining the same results, the techniques listed here are just what works for me.

You may also be interested in reading how to create control panels for your widgets.


53 Responses to “How To Create Wordpress Widgets”

  1. djole says:

    Very useful article. I am ready to create my personal plugin.
    Thank you.

  2. Glenn says:


    Nice tutorial. After doing this over and over again I created to tool to take the tedium out of creating WordPress Widgets. Take a look over at http://www.widgetifyr.com and let me know what you think.


  3. Angelika says:

    This was EXACTLY what I needed. Thank you.

  4. Conrad says:

    Really appreciate this tutorial. Nicely done – simple, quick and to the point. Nicely done.

  5. Neeraj Kumar says:

    This is a very good example. Since I come from a C++ background, it helped e a lot.

    Thanks again!

  6. Christher Lenander says:

    Thank you. This is what I been looking for. lots of articles about creating plugins but few about creating widgets.

  7. Pinyo says:

    Really excellent tutorial. I appreciate it! Definitely cut my development time in half.

  8. Kaitora says:

    Your plugin has been a great help for me to learn how to create some wordpress plugins. All of the other tutorials I have seen have not included anything on widgets. Thanks for the wonderful resource

  9. jim smith says:

    Thanks for the hello world style example.
    it was the best example i have found yet.

  10. KreCi says:

    Thanks man! That is so helpful! You will see my new widget plugin released soon!
    Happy New year 2010! :)

  11. BrandonSch says:

    Great post , You’ve really hit the
    nail on the head, I just don’t understand why people quite get it.
    I’m not for sure how many people I’ve talked to concerning this very
    thing in the past month, and they just can’t get it.

    , Excellent post!

  12. Mauricio Wolff says:

    Man… a lifesaver.

    Thanks a lot. This tutorial and the plugin “TS Custom Widgets” (that allows me to select wich widget should show on each page/post) makes wordpress even better.

    Tks a lot

  13. Pravin says:

    @Uppfinnarn, @Stubbornella: The tags aren’t mixed up. They are intented that way.

    Instead of using echo $before_title . 'My Widget Title' . $after_title;

    the author should have used
    echo $before_title;?>My Widget Title< ?php echo $after_title;

  14. Markus Freise says:

    Great tutorial to learn first steps. Thank you.

  15. Uppfinnarn says:

    There are tags in some of the latter examples; looks wierd…

  16. Gopinath says:

    Thank for your widget creation step by step explaination,its really awesome,,.

  17. manitra says:


    Thanks for this tutorial, it’s an excellent starting point.


  18. chocobee says:

    thanks for the tutorial. do u know any link that teach how to create advance widget?

  19. Stubbornella says:

    There are a couple of places where the tag got mixed in with your php.

  20. Vinicius says:

    Greate tuto….


  21. jigar says:

    really verry nice article for beginners and its working fine…. thanks …

  22. Christian says:

    Great article/tutorial

    How about writing about how to make options/settings for a widget. Thar would really be helpful…

  23. kelik says:


  24. Aod says:

    I’m trying to create a sidebar widget using the code at http://www.stopie6.com/widgets.html (Simple Text Message), but can’t work out which code to change in your example, and where to put the code in from the link? How would the php file handle that if statement?

  25. Njualem says:

    Excellent and Cristal-Clear, I can now get into making widgets for my website.

    Thanks a Million.

  26. seo free says:

    Thanks really helpful to create a plugin for wordpress..thanks lot..:)

  27. James says:

    I just created a Google Translate widget for my blog and it only took a few minutes thanks to your introduction. Thanks!

  28. Aakash says:

    Thanks very much. This is the thing i want !

  29. Jonathan Drain says:

    Great article! I found it very straightforward and helpful.

  30. Ian Kree says:

    Nice article. It tells exactly what I need to do.

  31. Abi says:

    What a simple solution to my problem. I do not know php but is right away going to try this simple methid to make extra widgets for my blog.

  32. gercek says:

    better than wordpress documentation. thanks.

  33. Davis says:

    I dont get any of the mubble jummble! please help me in a simple way!!!

  34. Phoenix says:

    Hello sir, i have a question. How can i create a title field for the widget so the user can rename it with whatever they like. I really blind about php and Wordpress coding. So could you tell me the code and where to place it. Don’t worry i can figure it out. Thanks:).

  35. Björn says:

    Thanx a lot for this nice tutorial … !!!

    Merry Christmas from Germany…

  36. Jeff R. says:

    I am a little confused by this line;

    &lt?php echo $after_title;

    Is that supposed to be an actual less than bracket, making an opening php tag?

    And, I thought when I started reading this that the Hello World example was just to show you the initial step. What is the purpose of it being called later in the function? I thought for an instant maybe we were supposed to put HTML in there, but you have the widget tags to use what the user theme has already…


    • Lonewolf says:

      You are correct about the php tag, it got converted to html chars along the way :(

      Not sure quite what you mean about calling the function? I guess your referring to the call to sampleHelloWorld() from within widget_myHelloWorld($args)? This is just to keep the different sections code separate. You can replace sampleHelloWorld() with whatever you wish.


  37. My Puppy654 says:

    uhhh….. i don’t get it! It looks to complicated! I thought it would be easy but i guess not….. i was planning on making a widget but now i guess not…. :(

  38. stratosg says:

    excellent man! very very very helpful thanks!

  39. Rana says:

    Very nice article. Thanks

  40. nkuttler says:

    Great article, thanks! I’ve already written plugins but never before a widget. This and your post about how to create control panels for widgets are very useful.

  41. Awshaal says:

    Thank you so much, such wonderful article.. A++++

  42. Anonymous says:

    Really Nice guide to aadd widgets

  43. chat says:

    thanks for all..

  44. software_developer says:

    Thank you. Also i’ve found good information about sidebar widgets development on http://blogs.helion-prime.com/henadiyatroshko/2008/04/14/simple-wordpress-sidebar-widget-step-by-step-development.html

    • Dimitar Stoyanov says:

      Great article! Really good introduction to widget basics.

      software_developer: thank for the nice link. Really helpful information about widget’s setup!

  45. Fareeha says:

    Thanks a bunch for the help.

  46. palPalani says:

    thanks for you information, this is what i&squot;m looking for… great!

  47. McLarty says:

    Thanks for the great &quot;hello-world&quot; …I&squot;m just getting started on a plugin!

    got any good links to the next steps? Eg. Calling a flash movie or creating options inside of WordPress for the plug-in?

  48. don says:

    Thx!! A nice and easy to follow explanation!


Pages that link here

  1. How To Create A Widget: Guide To The Best Web Widgets Creation Tools and Services « Argument
  2. rss_link_lateral: Mi primer Widget para Wordpress | Libro de Apuntes
  3. Alternate Recent Posts Widget

Leave a Reply