Custom Widgets

What is a Widget?

In WordPress, widgets are blocks of content that you can add to your site’s sidebars, footers, and other areas.

WordPress comes with a number of default widgets, which are found in the folder wp-includes/widgets. There, you will find category lists, menus, galleries, forms, etc. The complete list as of this writing is:


In order for a widget to appear in a theme, you must first register it, as show in this tutorial.

Customizing a Widget

Suppose we want to customize a widget – class-wp-widget-categories.php. Why would we want to do this? Well, this widget outputs categories in specific way:


What if I wanted these categories formatted differently? What if I wanted to remove the heading Categories, and give the <ul> a class? How would I do this?

For this example, we have a hardcoded html category list that we want to replace with a category widget. In other words, we want to output the categories in a way that matches what we’ve hard-coded here:


That code renders to this:

custom categories

The default wordpress category widget will output this:


The default categories widget renders this:

default widget

Rather than customize a wordpress widget (NEVER make changes to wordpress core) we are going to create a custom categories widget based off of the default categories widget. The first thing we do is to create a folder entitled widgets in our theme folder. Copy the file class-wp-widget-categories.php to that folder. When we are finished, our custom widget will be available to us when we use this theme. It will not be available when using another theme.

Next, you need to include that file on your functions.php file. “require once();” with the path/name of the file in brackets. Place this at the top of functions.php:


If we now visit the site, we will get a fatal error: Fatal error: Cannot declare class WP_Widget_Categories, because the name is already in use This is because we are declaring the class WP_Widget_Categories twice, and you cannot declare a class more than once without using namespaces. To solve this, we will rename the class.

First, let’s register the widget. The code to register a widget is this:


We want to specify what the widget is by passing its name – WP_Widget_Categories_Custom – in the parameters (done by placing it in the brackets):


Then we will add the action using add_action, pass in widgets_init as we want this to run, and then add the custom_register_widgets function:


Now we want to style the custom categories. Open up widgets/class-wp-widget-categories.php. On line 17 you should see this:


Remember that we have renamed this class. It’s now called “WP_Widget_Categories_Custom”, so we will edit that line to read


Refresh the page now and you will see now errors. That is because we have renamed the class; WP_Widget_Categories is no longer being called twice. Instead, WP_Widget_Categories is called once, and WP_Widget_Categories_Custom is called once.

Go into your admin under Appearance >> Widgets and place a category list inside this widget.

Now let’s replace the hardcoded list of categories (and surrounding divs) with the following, in order to show the custom categories widget:


Refresh the page and you will see that the category list is identical to the default category list. That is because we haven’t yet made any edits to our custom category widget. Lets begin by editing out Heading “Categories”. (This will also let us know that the correct file is being used. If the correct file is not being used, the edits will not show). Find the following on the WP_Widget_Categories_Custom and comment out the line that echos “Categories” by placing two forward slashes in front of the line:


Now let’s find where the list begins on our custom WP_Widget_Categories.php and add the class to style the list. Look for ul and add the class to it. In our case, this is w3-ul. In your case, it is whatever class (or classes) style the list on your hardcoded html template. We can also add a link back to the home page:


Refresh our page, and the widget will output the categories with the exact appearance of our hardcoded template. Clicking on any of those links will take us to the appropriate category page.