Beginners Guide For Creating a Simple WordPress Widget

WordPress widget development

Among the various features of WordPress, custom widget is one of the most common and powerful ones. By using the widgets correctly, you can make the sidebar much more useful for the users. A unique feature of the widgets is you can use them anywhere you like, be it header, footer, sidebar or in the content section too! It is up to you to decide where you want to put the widgets.

Before going too deep, let’s first make sure that we are on the same page when I refer to widgets. Widget is an exclusive WordPress feature that provides a drag and drop area for the general users. Widgets can perform lots of different things depending on how they were developed.

where to put WordPress widgets

I assume that you already know how to use widgets in your WordPress website. You can go through the official page for a complete overview of WordPress widgets.

However, I know most of you are lot more advanced than just dragging and dropping widgets. The following discussion is exclusively for you. Let’s get started.

Where to Put Widgets

When it comes to providing widgets, you have two options. You can place the widget in a plugin or include it in the theme. If you provide it with a theme, the widget will be readily available once the theme is activated. But it won’t be available once the user has changed that theme. If you include your widget as a WordPress plugin, it will be available as long as the plugin is activated.

Whether to put the widget in a theme or in a plugin is a matter of personal choice and requirements. If you ask me, I prefer including widgets in the theme. While I don’t support the idea of bloating up the theme with all sorts of features, I think widgets have more to do with looks than performance. And anything related to looks should be added to the themes.

Try to understand whether you will need the widget without having to depend on a theme. If not, then you can safely add the widget to your theme. But if you need the widget regardless of the theme, then you have to go for the plugin way.

In this article, we will discuss how to create a widget in a theme. However, I will briefly discuss about creating the plugin version of our custom widget below.

Putting the Widget in a Plugin

You may have thought WordPress plugins are long PHP files with several directories and sub-directories. But that is not always true. A plugin could be of a single PHP file. Actually, that is what I will do now. I will create a plugin consisting of one file only.

To create a new plugin, go to your WordPress installation directory and navigate to wp-content -> plugins.

Create a new PHP file for your plugin. You can name it anything you want as long as it does not conflict with WordPress naming standards. You should name your plugin after what it does.

Now, open the file in a text editor. I use Sublime Text 3 and Notepad ++ for editing purposes. You can use any other text editor but they are the most recommended.

Paste in the following below code right on top of the file. Remember, you should not put anything before this code block, not even a line break or a space.

Plugin Name: Name Of The Plugin
Plugin URI: http://URI_Of_Page_Describing_Plugin_and_Updates
Description: A brief description of the Plugin.
Version: The Plugin's Version Number, e.g.: 1.0
Author: Name Of The Plugin Author
Author URI: http://URI_Of_The_Plugin_Author
License: A "Slug" license name e.g. GPL2  */ 

The above code is directly copied from WordPress codex. You should update with appropriate details of your own plugin. After updating the file with your personal details, save the file.

Log into your WordPress dashboard and go to Plugins –> Installed Plugins.

If you have followed me closely, then you should see your newly created plugin in the list.  You have just created your first ever WordPress plugin. Hurray!

first WordPress plugin

Okay, let’s settle down now. As I said, I will limit my discussion about creating plugins. This is pretty simple and appropriate for the beginners.

You can activate your plugin now. But don’t expect it to do to anything because as you haven’t provided anything yet. Continue reading the instructions for the theme version of our widget.

After you have copied all the codes, make sure that the content of your plugin file matches the code of ‘Wrapping it Up’ section below. Save the file and go to the widgets list. You should see your new widget there.

Background of a Widget: OOP in WordPress

Creating custom widgets is one of the few times when you have to deal directly with object-oriented code in WordPress. Most new WordPress developers find it challenging that they have to deal with Object Oriented PHP (OOP) for creating custom widgets.

However, as OOP is not fully applied into WordPress yet, you can still get around without knowing object oriented coding inside out. But when it comes to developing widgets, I strongly oppose the idea of bypassing OOP.

Don’t despair if you are not at home with object orientation. Developing WordPress widgets does not require you to be an OOP guru. Rather, you will do fine with a basic understanding of the concept. If you are at least familiar with class, object, extending etc., then you are good to go.

Otherwise, take a look at this article, it will provide you with the information you need to get going for now.

Creating the Widget: Getting Started

Before writing the code, I will give you an overview of the things we are going to do. In order to create a widget in WordPress, we have to extend the default WP_Widgetclass. This can be done by creating a new class, which will automatically inherit the properties and methods of the WP_Widget class.

Next, we have to add some custom functionality which will make our widget unique among others. Our finished widget will look like this –

creating the widget

By convention, we are required to include at least one method on your widget. As we are doing this from a basic level, we will include one method in our custom widget. As we have to output something too, we will echo a test statement as the output.

All the code we will write in this tutorial should be added just before the closing php tag of your theme’s functions.php file.

Make sure not to leave any space or a blank line after the closing PHP tag as your theme will then return error.

So, our code will look like this –

class My_First_Widget extends WP_Widget {
public function widget( $args, $instance ) {
echo 'My First WordPress Widget !!';
} }

Now, that will do nothing more than echoing the statement. But, don’t expect the widget to start working yet. We have to let WordPress know that we have created a custom widget.

Adding the Widget to WordPress

Creating the widget method, extending the WP_Widget class did all the hard work of creating a widget, but we need to inform WordPress that we have created an awesome widget.

To do that, you have to ‘hook’ your widget by adding this code block just after the previous codes-

add action( 'widgets_init', 'my_first_widget');
function my_first_widget() {
register_widget( 'My_First_Widget' );

By hooking, you are instructing WordPress that when widgets_init part is being processed, it should register our custom widget.

Continuing with the Widget

If you have followed me closely, then you have developed your first WordPress widget already, congratulations! However, you will notice that your widget does not have any distinctive label or description about what it does. In order to add these, you have to make a constructor for your widget.

It will provide the widget with a label and a short description.

Paste this code after the widget() function –

function __construct() {
parent::__construct( 'my_first_widget', // Base ID of your widget
__('My First Test Widget', 'text-domain'), // Widget name
array( 'description' => __( 'This is the first ever WordPress widget developed by me.', 'text-domain' ),) // Widget description


Though the code block looks challenging for beginners, it is pretty straightforward. Let me explain:

There are some pre-defined requirements of the construct method; we used some of them. By parent::__construct, we are making sure that the required information is provided accordingly when the parent method is called.

  1. The first parameter is ID of your custom widget.
  2. Second one is the name that will be displayed on the widgets list.
  3. The third and the final one is an array, which contains a short description of the widget.

At this point, if you refresh your widgets list, you will be able to see your new widget along with the default ones.

new WordPress widget

Wrapping it Up

So, after adding all these codes, the final version of the widget code should be this –

classMy_First_Widget extends WP_Widget {
public function widget( $args, $instance ) {
echo 'My First WordPress Widget !!';

function __construct() {
'my_first_widget', // Base ID of your widget
__('My First Test Widget', 'text-domain'), // Widget name
array( 'description' => __( 'This is the first ever WordPress widget developed by me.', ' text-domain ' ), ) // Widget description

add_action( 'widgets_init', 'my_first_widget');
register_widget( 'My_First_Widget' );

Beyond the Basic

You don’t want your widget to be only capable of sitting in the widgets list and displaying a single line, right? It is obvious that you want to complement the users browsing experience with various options of the widget.

The first thing you can do to enhance your widget is to allow it to collect and save user data in the database. That will allow the users to input and view the data in various forms. These could be done by using the ‘form’ and ‘update’ classes.

As this article is only intended for beginners, I will limit the discussion within a summary of these two classes. The ‘form’ class will allow you to provide all type of HTML input form tags to the users. It will take the inputs provided by the users and process them for saving in the database.

The updated class makes sure that the provided data is valid and does not contain any malicious code. Then it saves the data in the database so that you can later retrieve or use the data accordingly.

More Resources:

If you are looking for some next-level tutorials about WordPress plugins or widgets, you can check out these post:


Obviously, there are lots of other useful tutorials out there which I may have missed. If that is the case, don’t hesitate to inform me about them.

I think that’s enough for creating your first WordPress widget. I believe I have provided enough information to get you started. Read some more tutorials on creating WordPress widgets, make your hands dirty with some real coding, and you will be a widget expert in no time.

Nonetheless, if you still have any confusion about creating a custom WordPress widget, shoot a comment below. It will be my pleasure to help you.

Leave a Reply

Your email address will not be published. Required fields are marked *