How to Code Your Own Custom WordPress Widget
What if you want to grab a bit of content from your website database and display it in a widget? The solution is to code up a custom sidebar widget. While that may sound like a daunting task, as long as you have basic PHP skills it is within your reach.
So follow along with this tutorial and you’ll learn how to create two different widgets:
- A simple widget that displays the widget title, site title, and site tagline.
- A slightly more complex widget that displays a list of all categories sorted alphabetically and split into two columns.
Ready to learn the basics of custom WordPress widget creation? Let’s get to it.
WordPress Widget Building Basics
You’ll need three things in place in order to follow along with this tutorial:
- A WordPress development environment
- Basic PHP coding skills
- Basic WordPress development experience
All it takes is a single errant comma or missing curly brace to crash a WordPress website, and if you’re relatively new to programming, your site could be down for several minutes or longer while you try to locate the offending code. For that reason, you should absolutely get your widget working using a local development environment before you try using it on a live website.
If you’ve never written a line of PHP or coded up a basic WordPress plugin, then this tutorial may be a bit out of your reach. However, the good news is that you can learn everything you need to know either informally by working through our series on WordPress Development for Beginners, or formally by enrolling an upcoming course at the Academy.
If you meet those three basic requirements, you’re ready to start slinging code. Let’s get to it.
The WordPress Widgets API
You create a new WordPress widget by adding code to one of two places:
- A custom plugin, which you should use if you want to use the widget with more than one theme or on more than one website.
- The functions.php file of the active theme — which should be either a child theme or a completely custom theme.
Just for the sake of example, you can find the completed code for the simple sidebar widget described in this tutorial available at GitHub. If you aren’t sure where to write your code, or just want to see the entire code at once, download a copy of that plugin.
WordPress widgets are created with a bit of object-oriented programming. The
WP_Widget class is extended to create each widget. The
WP_Widget class includes close to 20 different methods. However, for basic widgets, you really only need to use four of them:
__construct(): registers basic widget information.
widget(): contains the widget output — what you actually see on your site front end when the widget is added to a widget area.
form(): defines the widget settings displayed in the WordPress admin area.
update(): updates widget settings when new settings are saved in the WordPress admin area.
Example Widget #1: Displays the Widget Title, Site Title, and Tagline
The first thing to do is to extend the
WP_Widget class like this:
In this case, the name of the new widget function is
jpen_Example_Widget. Note that jpen is simply a prefix I add to all custom functions to avoid conflicts with any functions in other plugins, themes, or the WordPress core. You can use any name that is appropriate for your widget, and add a prefix if you want to follow best practices.
We’ll write functions using the four methods mentioned in the list above and nest all four inside of our widget function. Then, in the last step, we’ll write a function to register the widget.
Let’s start the method writing process with the
__construct() method is used to assign an id, title, class name, and description to the widget. Here’s how the constructor function looks to create our first example widget:
To understand this function, start with the line that begins with
parent::__construct(). What’s going on is that this line creates a new widget with the id of
'example-widget', the name
'Example Widget', and two widget options: a class name and a short description.
All of this code goes inside of
jpen_Example_Widget and is used to register the widget with WordPress and then display the widget title and description in the admin area.
The next step is to use the
widget() method to define the widget output that will be displayed on the site front end.
widget() does is contain the code that generates the actual content displayed by your widget. The contents of
widget() could be just about anything but generally will include some PHP. Otherwise, you would just use the text widget built into WordPress.
In our case, we’re going to give users the option to display a custom widget title. So we’ll need to grab that title and then use
get_bloginfo() to display the blog title and tagline. Here’s the code we’ll use to do that:
There a couple of things going on in that function that you’ll want to take the time to understand:
$args: this variable loads an array of arguments which can be used when building widget output. The values contained in
$argsare set by the active theme when the sidebar region is registered.
$instance: this variable loads values associated with the current instance of the widget. If you added a widget to the sidebar twice, each
$instancewould hold the values specific to each instance of the widget.
widget_title filter: returns the title of the current widget instance.
get_bloginfo(): a function that can be used to return all sorts of meta data about a WordPress website including the site name and tagline.
After defining a few variables using the information in the list above, the code then goes on to produce the actual output which consists of information from
$args, the title, and the site name and tagline.
Note that virtually every widget should include the
'after_title' arguments. They are necessary to ensure each widget is nested inside the theme-specific HTML tags.
widget() method should be nested inside of
form() method is used to add setting fields to the widget which will be displayed in the WordPress admin area.
1.6 million WordPress Superheroes read and trust our blog. Join them and get daily posts delivered to your inbox - free!
Widgets that include a lot of options will be quite complex in this department. However, in the case of our example widget, all we want to do is allow users to assign the widget a custom title. So things are pretty simple.
This function returns the current values of this particular instance of the widget by calling the
$instance parameter. We then check the current instance information to see if the title is empty. If it isn’t, we display the current title.
Next, the label and input elements nested inside of paragraph tags create a labeled input field for the user to add a new title.
With this bit of code added to
jpen_Example_Widget, widget settings will look like this:
The next step is to update the information in the WordPress database using the
This method takes two parameters:
$old_instance. The first contains the values added to the widget settings form. The second contains the existing settings — if any exist.
update() method should validate the new settings as appropriate and then assign them to the
$instance variable and return that updated variable. If that sounds a bit complex, the following example should clarify things.
In the case of our example widget, all we’re doing is updating the title. So all we need to do is:
- Grab the title from the new instance,
- Strip away any HTML or PHP tags that may have added to the widget title,
- Assign that title to the instance, and
- Return the updated instance.
Register the Widget
The final step in the process is to register the widget using the
add_action function and the
widget_init hook. Here’s how to do it:
First, we create a function to register the widget and use the widget object name to identify it. Next, we tie the registration function to WordPress using the
widgets_init hook and the name of our registration function.
This bit of code is added outside of
jpen_Example_Widget. When it is called it will pull up the widget with the appropriate name,
jpen_Example_Widget in this case, and run all of the code contained in the widget.
With this final bit of code in place we can add our widget to a sidebar, configure it to our liking, and display our site title and tagline in the sidebar, like this:
Example Widget #2: Displays Categories in Two Columns
A little while back I wrote a tutorial explaining how you can turn any HTML5 template into a WordPress theme. However, what I didn’t do in that tutorial is recreate any of the sidebar widgets included in the template. So our second example widget will be the category list sidebar widget from the Blog Post HTML5 template by Start Bootstrap.
Here’s how the sidebar widget looks in the original HTML5 template:
Recreating this widget requires a bit more code than our simple example widget, but in reality it isn’t very complex. As a matter of fact, the
update() functions are basically unchanged. The only real difference between this widget and our previous example is that the
widget() output method includes quite a bit more code.
The reason for this is that to create the widget content we need to generate a list of all the categories, sort the list into alphabetical order, and then arrange the categories into two columns. While there are a variety of ways this could be accomplished, here’s one way to get the job done.
For starters, I created the
Next, I created a few variables:
The title and category variables are pretty self-explanatory. They hold the widget title and a list of all categories.
$cat_count variable will be used to keep track of the total number of categories so that we can sort them into two lists. The two column variables,
$cat_col_two will be used to divide the categories into two columns.
Next comes the function that iterates through all the categories and splits them into two columns.
For each category, the
$cat_count variable iterates and a
$category_link is created. Then, based on the current
$cat_count — whether it’s even or odd — the
$category_variable is added either to the column one or column two variable.
In addition, this code also nests each category into a list item with a class of
"list-unstyled" to match the classes and HTML used in the original template.
Finally, we need to actually print out
$cat_col_two to render the list of categories:
That code iterates through each of the category column variables and prints out each list of categories into a div. The classes and HTML structure assigned to the widget mirror the classes and structure included in the original template to ensure that the styling included in the original template CSS resources is properly applied to the new widget.
Here’s how the sidebar widget looked upon completion. If you take a look back at the original version in the template in the image above, you’ll see that it’s a perfect match!
If you’d like to see the full code that creates this sidebar widget, look for the
jpen_Category_List_Widget instance of the
WP_Widget class in the functions.php file of the Simple Blog Theme at GitHub.
Creating Your Own Custom Widget
Creating a custom sidebar widget involves working with the rather complex
WP_Widget class. While it may seem a bit daunting, the good news is that you can boil down the process to five steps:
__construct()to define the basic widget information.
widget()to define the widget output.
form()to create the admin settings menu.
update()to update widget settings.
add_action()to tie the widget object to the proper hook.
While creating a custom widget may be a bit complex, there’s a relatively narrow body of knowledge you need to master to create powerful custom widgets. Wrap your head around those five functions and you’ll be able to turn just about any idea you can dream up into a WordPress widget.