How to Create a Simple Custom WordPress Widget

This website is built on WordPress, and I recently needed to create my own WordPress widgets. I am not a programmer, but I know enough code to make me dangerous. So after quite a bit of research and trial and error, I’ve been able to create some very basic widgets for this website.

Why I Needed Custom WordPress Widgets

I have very specific needs, and I found myself using the Text widget frequently to put custom information and code into the sidebars.

Here’s an example…

Text WordPress Widgets

As you can see, I had added several Text widgets, but without expanding them I had no idea what was in them. Sure, I could enter a “title,” but I often don’t want that to appear within the widget. This makes it extremely difficult to keep track of what widget holds what without expanding each Text widget.

Additionally, I have several different templates, each that may hold some of the same content. I’ve been copying and pasting the same code into different Text widgets, which is very cumbersome when I then need to edit that code. I can’t just edit one — I have to edit them all.

I didn’t need anything complex. I needed to be able to create a widget that could be used in multiple places, and that was properly labeled.

Create a PHP File

The first thing you’ll need to do is create a PHP file and name it [pluginname].php and save it in your plugin directory.

Following is what should go into that file. Replace all red code with your own (without brackets, of course).

/* Plugin Name: [Enter name of your plugin here]
Plugin URI: [Enter your website URL]
Description: [Enter brief description of plugin]
Version: [Enter version number of plugin (probably 1.0)]
Author: [Enter your name]
Author URI: [Enter your website URL]

class [PluginNameWithoutSpaces] extends WP_Widget {
          function [PluginNameWithoutSpaces]() {
                    $widget_ops = array(
                    'classname' => '[PluginNameWithoutSpaces]',
                    'description' => '[Enter brief description of plugin]'

                    '[Enter plugin name]',

          function widget($args, $instance) { // widget sidebar output
                    extract($args, EXTR_SKIP);
                    echo $before_widget; // pre-widget code from theme
print <<<EOM

[Enter code that will appear in your widget here]

                    echo $after_widget; // post-widget code from theme

          create_function('','return register_widget("[PluginNameWithoutSpaces]");')

Between the EOM’s is where you’ll enter the information that will show up in your widget. So whatever it is that you would have put into a Text widget, you’ll enter here.

Activate Your Plugin

That was pretty simple, right? Now let’s go to your Plugins and find the one you just created. The one I created is called Loomer Newsletter Sign-up Form…

Custom WordPress Plugin

Just click Activate like you normally would.

A couple of things here. You’ll note that I start all of my custom plugins with “Loomer.” You should have a naming convention for your plugins, starting with the same word so that they are easy to keep track of.

Second is that a custom plugin is a great solution for newsletter form code like this. It’s something I will place on most pages, but it’s also something that may change. When it does inevitably change, I’ll just go into the original code and change it once.

Use Your Widget

Now that the plugin is activated, we can use it like any other widget. Just go into your widgets, find it and drag it…

Custom WordPress Widget

Note that my widget says “There are no options for this widget.” That’s right, there aren’t. We already created it. This is as simple as it gets.

Now when I go to my website, every place where I use this widget, I’ll see this…

Custom WordPress Widget Newsletter

You just created your own widget. Pretty cool, right?

Add Complexity

In a perfect world, I would not need to go into the PHP file to edit this plugin every time I need to make a change. I’d have an admin page specifically for the plugin. I’m working on that, but looking for the simplest, most basic solution possible.

If you’re a programmer and have the answer, please share!

  • Pingback: How To Bundle A Pre-Defined RSS Widget With Your WordPress Theme | Andrew Riley()

  • Pingback: How To Bundle A Pre-Defined RSS Widget With Your WordPress Theme - Keen Meanie Design()

  • Love Fabillar

    Thank you, that was the ultimate guide to creating plug-ins. You provided the exact code anyone would need, & that is why I am bothering to comment just to thank you.

    • Jon Loomer

      Hah! Thanks, Love.

  • tips101

    An admin page? Do you mean admin options, or just something like the edit theme / plugin pages it shows up if you’re editing a plugin?


  • greentub

    What do you use to create the PHP file? A text editor like TextEdit or Text Wrangler? Just save it with a PHP extension?

    • Jon Loomer

      Yeah, I use TextEdit.

  • Mohammad

    thank you for article.
    it was great :-)

  • Wisitech

    Thanks you so much…..
    it was great :-)

  • Pingback: Articles | Pearltrees()

  • Nizul Zaim

    Thanks.. your guide the simplest guide between others guide.. Have screenshot to know what exactly my widget will show..

  • Mittul Chauhan

    very useful post indeed .. thanks a lot for taking your valuable time for us …

  • faospark

    thank you for this one, i hope people do realize after reading this that creating a simple widget is not that hard.

  • Chad Foreman

    Awesome tutorial! Thank you so much for this one. Bookmarked.

  • Pingback: Create a Simple Custom WordPress Widget |

  • Seth

    Hi, this post was very helpful for setting up a widget from scratch, and fast!


    > &

    • Seth

      Also, I think it might be helpful to show how to add some “admin” functionality. Here is a (very) brief description of how to add a custom field:
      right before the

      function widget($args, $instance) { // widget sidebar output insert this code:

      function form($instance)
      $instance = wp_parse_args( (array) $instance);
      <p><label for=”<?php echo $this->get_field_id(‘myValue’); ?>”>My Custom Value<input id=”<?php echo $this->get_field_id(‘myValue’); ?>”
      name=”<?php echo $this->get_field_name(‘myValue’); ?>” type=”text” value=”<?php echo $instance[‘myValue’]; ?>” /></label></p>
      function update($new_instance, $old_instance)
      $instance = $old_instance;
      return $instance;

      the form function is what makes the option field show up in the widget control panel. the update function handles applying those changes to the widget. to then access the value in the widget, after the EOM; line, do this

      echo “My custom value is: <b>”.$myValue.”</b>

      add new <p><label…> blocks for each element you want, then make sure to add the same lines for it in the update function and your widget function.

  • Lohith

    Hi.. I have created a plugin as you instructed but its not showing in the list of plugins what i should do to activate it.. how to make visible in the list of plugin

  • kay

    I am not sure how others are getting this to work? i keep getting a fatal error with this code when i try to activate the plugin-unexpected end? But i doublechecked all your brackets and they seem to be correct. i dont even have any content in there yet – just ‘your code will show up here’. also dreamweaver flags this line as having a syntax error:

    echo $after_widget; // post-widget code from theme

  • lohith

    What is the problem in my coding.. its not getting activate showing

    Plugin could not be activated because it triggered a fatal error.

    Parse error: syntax error, unexpected T_STRING, expecting T_FUNCTION in D:xampphtdocswordpresswp-contentpluginswelcomewelcome.php on line 38

    My code goes here.. need help…!!



    Plugin Name: Welcome Widget

    Plugin URI:

    Description: Lets test

    Version: 1.0

    Author: The Boss

    Author URI:


    class welcomeWidget extends WP_Widget


    function welcomeWidget()


    parent::WP_Widget(false,$name='Welcome Widget');


    function widget($args, $instance)



    $title = apply_filters('widget_title',$instance['title']);

    echo $before_widget;



    echo $before_title . $title . $after_title;


    echo $after_widget;


    function update($new_instance, $old_instance)


    return $new_instance;


    function form($instance)


    $title = esc_attr($instance['title']);

    echo 'get_field_id(‘title’).'” name=”‘.$this->get_field_name(‘title’).'” type=”text” value=”‘. $title.'”/>';



    function welcomeWidgetInit()






  • Max Farhad

    There is nothing wrong with the code in this example. The reason why dreamweaver shows errors or if the plugin falls to activate is because of poor coding in the part of people using this plugin. The reasons why the errors show is because of the quotation marks or comma used in your own code.

    The rule to insert a quotation inside a PHP/javascript string is to add a before it :

    so for example you for alt=”some image text” you have to change it to alt=”some image text”

    Hope this helps the people having problems activating their plugin.

    Millions thanks for Jon Loomer for teaching me in this one example how to write widgets. Jon you are awosome :-)

  • Borag Thungg

    Cheers Jon. Just what I was after. A really simple tutorial for creating a custom widget plugin. Nice.

  • james g

    does not work, wont activate saying there is Parse error: syntax error, unexpected $end in /home2/entechpc/public_html/wp-content/plugins/leacroftwidget.php on line 40 .

    even when i do not put anything in there, when I do, it is simply text with some p tags and an h3 tag, not sure what the prob is but i have not gotten it to activate.

  • yassershaikh

    Hey ! nice post. I saw the social share you use on your website, i liked it very much. Can you tell me which plugin you are using for this ?

    • Jon Loomer

      That’s Flare!

      • yassershaikh

        thanks for the info mate !

  • José Monteiro
  • ok


  • ok

    widget not working

  • ok

    what can i do?

  • Judy

    Thank you very much for this post, it is one of the best I have seen to help you get started. I appreciate greatly the time you took to put this together.

  • Andrew

    This is such a straightforward guide to making a custom WordPress widget. Thanks!

  • vinoth

    Hope many coding related information is missing like

    1. Register widgets-init

    2. Register_widget

    3. Class structure

    This may help to guide

  • Baidya nath Singh

    Very useful information, creating a widget and some hints on how to create a plugin. Way of writing post is interesting. I like it.

  • kera mchugh

    brilliant instructions :) thanks for sharing your trials & errors with the rest of us. Much appreciated when these kinds of instructions come from other non-programmers… worked like a charm.

  • manikandan

    thanks it will help me a lot

  • Tarmizi Achmad


  • Shashank Bhattarai

    I tried to use it but its making my widget sticky, What to do to make it non sticky. I want to place it after 3 widgets in my please

  • barth

    hi please give me the html markup of the example newsletter widget of this post thanks.

  • Keyur

    Wow, that’s perfect and simplest way to create a plugin I have ever learnt. Thanks Loomer

  • Native Imaging

    Thank You for this article, however it seems that I only get one instance of the custom widget. Would you know of any references to make my custom widget to allow infinite instances?

    I looked through the wp-includes widget.php and found this function, but i’m not sure if its the correct way to enable infinite instances:


    * Convert the widget settings from single to multi-widget format.


    * @since 2.8.0


    * @return array


    function wp_convert_widget_settings($base_name, $option_name, $settings) {

    // This test may need expanding.

    $single = $changed = false;

    if ( empty($settings) ) {

    $single = true;

    } else {

    foreach ( array_keys($settings) as $number ) {

    if ( ‘number’ == $number )


    if ( !is_numeric($number) ) {

    $single = true;





    if ( $single ) {

    $settings = array( 2 => $settings );

    // If loading from the front page, update sidebar in memory but don’t save to options

    if ( is_admin() ) {

    $sidebars_widgets = get_option(‘sidebars_widgets’);

    } else {

    if ( empty($GLOBALS[‘_wp_sidebars_widgets’]) )

    $GLOBALS[‘_wp_sidebars_widgets’] = get_option(‘sidebars_widgets’, array());

    $sidebars_widgets = &$GLOBALS[‘_wp_sidebars_widgets’];


    foreach ( (array) $sidebars_widgets as $index => $sidebar ) {

    if ( is_array($sidebar) ) {

    foreach ( $sidebar as $i => $name ) {

    if ( $base_name == $name ) {

    $sidebars_widgets[$index][$i] = “$name-2″;

    $changed = true;

    break 2;





    if ( is_admin() && $changed )

    update_option(‘sidebars_widgets’, $sidebars_widgets);


    $settings[‘_multiwidget’] = 1;

    if ( is_admin() )

    update_option( $option_name, $settings );

    return $settings;


  • Dorival Cardozo

    Very very good tutorial, deserves teh google first page ! thank you

  • ritchieee

    Such a shame, seems like a quick little tutorial but like many others I can’t seem to get it to work because of the fatal error.

  • ronh

    This really great, clear and concise, thanks Jon. When I can, I’m going to have a better look around your site. I’ve been bogged down with this widget thing for a while.

    And please, what is that plugin you have for bookings in the sidebar, it looks great.

  • Neithien

    hey, i’m just getting strated with WordPress, and this tutorial was verry helpful. But I have one question…
    I would like to make my widget do this:

    function writeMsg() {
    $t = date("H");

    if ($t < "10") {
    echo "Have a good morning!";
    } elseif ($t

    I’m working on it for almost 2 weeks and i just can’t get it to work! :(
    Can you help me?
    Sorry for bothering you.

    • Neithien


      function writeMsg() {

      $t = date("H");

      if ($t < "10") {

      echo "Have a good morning!";

      } elseif ($t

      sorry it just disapeared when i posted the comment :(

  • amit

    thanks buddy you rock take care