Skip to content

Creating WordPress Widgets: The Complete Guide

This Course teaches you how to use WordPress’s Widgets API, to both create WordPress widgets and register WordPress widget areas. If you’ve ever wanted to create widget areas (sidebars), or to fill your widget areas with custom-built widgets, this course is for you!

Before we dive in, we want to thank you for reading WPShout, and invite you to do a few things:

  1. Please comment freely on our articles with any questions, corrections, suggestions, etc. We love to hear from readers—it helps us understand how you guys are interacting with what we write.
  2. If there’s a topic in WordPress you’d like us to cover, tell us about it! We love to dive into the parts of WordPress that people would like the most help with. You can contact us directly at

And one additional thing! If you’re looking to learn WordPress development, we’ve written the best guide to it out there:

The Best Way to Learn WordPress Development

Get Up and Running Today

Up and Running is our complete “learn WordPress development” course. Now in its updated and expanded Third Edition, it’s helped hundreds of happy buyers learn WordPress development the fast, smart, and thorough way.

Here’s what they have to say:

“I think anyone interested in learning WordPress development NEEDS this course. Watching the videos was like a bunch of lights being turned on.” -Jason, WordPress developer

“Other courses I’ve tried nearly always lack clear explanations for why WordPress does things a certain way, or how things work together. Up and Running does all of this, and everything is explained clearly and in easy-to-understand language.” -Caroline, WordPress freelancer

Onto this Course: our full guide to creating your own WordPress widgets and widget areas.

1. Understanding the Basics of Object-Oriented Programming

WordPress’s widgets system (or “Widgets API”) makes use of a specific programming style called object-oriented programming, or OOP. Every WordPress widget is actually a WP_Widget Object—meaning an individual instance of the broader WP_Widget Class.

So our first step to program WordPress widgets is to understand the basics of object-oriented programming (OOP).

Object-Oriented PHP for WordPress Developers

Key Point: Classes and Objects

A Class is an abstract description of a type of thing. Once you’ve defined a Class, you create actual Objects of that class. The article uses the example of a Chair class:

// Creating the Chair class
class Chair {
    // Here we list important elements that all Chairs have,
    // like "height" and "color"

// Creating a Chair object
$mychair = new Chair;

Key Point: Properties and Methods

A Class’s properties define attributes that each Object has, and a Class’s methods define functions that each Object can perform. For example, each chair might have a color property, and a rock() method:

class Chair {
    public $color;
    public function rock() {
        // Details of the rock() method

While all chairs have the color property, we decide the actual color of each individual Chair object. One Chair might be green, while another might be red:

$mychair = new Chair;
$mychair->color: 'green';

$secondchair = new Chair;
$secondchair->color: 'red';

And when we’ve created our Object, then we can call its methods:

$examplechair = new Chair;

// Call the rock() method on the new object

If you understand the raw basics of OOP—Classes, Objects, Properties, and Methods—you’re ready to get into creating WordPress widgets.

2. Creating a Very Basic WordPress Widget

A widget is something—it can be anything!—that you drop into a WordPress widget area, such as a sidebar. This article covers creating a very basic, but functional, widget.

A Complete Guide to Making Your First WordPress Widget

Key Point: Register Your Widgets in a Plugin

Most widgets are best placed in a plugin—not in your theme—because you don’t want them to disappear if you switch themes. The article links to our tutorial on writing plugins—it’s much easier than you might think.

Key Point: The Minimal Code for a Widget

The code below, placed into the main PHP file of a properly registered plugin, will create a working widget. When you place that widget into a widget area like your sidebar, it’ll output the text “First WordPress Widget! Yay!” wherever you’ve put it.

// Create the First_WordPress_Widget class
class First_WordPress_Widget extends WP_Widget {
    public function widget( $args, $instance ) {
        echo 'First WordPress Widget! Yay!';

// Register the new widget at the widgets_init action hook
add_action( 'widgets_init', 'first_wp_widget');
function first_wp_widget(){
     register_widget( 'First_WordPress_Widget' );

3. Creating A Complex, User-Editable WordPress Widget

Most widgets will want to accept user input: for example, a “social follow” widget will want to ask the user the addresses of her social media accounts and which accounts to list. This article goes deep into a fully functional “Now Playing” widget that lets the user put a playable “favorite song” link in her sidebar.

Creating Dynamic, User-Editable WordPress Widgets

Key Point: form(), update(), and widget()

The Widgets API isn’t as simple as it could have been, and the code for this widget (or any really useful widget) is complex and extensive. As you read through the article, remember that the code is organized into three functions of primary importance: form(), update(), and widget().

Each of these functions is a method of the Class we’re defining, which in this case is WPShout_Favorite_Song_Widget. All of the heavy lifting takes place within the class definition for WPShout_Favorite_Song_Widget itself.

So although the plugin’s full code at the bottom of the article looks scary, there are really only four major pieces:

  1. Hooking into widgets_init, as we covered above
  2. Within the definition of WPShout_Favorite_Song_Widget, writing out the specifics of form()
  3. Within the definition of WPShout_Favorite_Song_Widget, writing out the specifics of update()
  4. Within the definition of WPShout_Favorite_Song_Widget, writing out the specifics of widget()

There’s a lot here, so take your time seeing how the pieces fit together. And feel free to take the fully-working code and adapt it to your own needs—that can be a great way to learn and to get results quickly.

4. Registering Your Own Widget Areas

Like socks go in a sock drawer, widgets go into widget areas. This article covers how to “widgetize”—create widget areas for—all different areas of your site, from your sidebar to your header to your footer to your homepage.

All You Need to Know About Making Widget Areas in WordPress Themes

Key Point: “Sidebar” and “Widget Area”

A sidebar is one type of widget area. Some widget areas are located in the theme’s sidebar, but not all are.

The relationship is as follows: a sidebar is one type of widget area. Some widget areas are sidebars—meaning simply that they show up in their theme’s sidebar, a column next to the main post content—but not all are.

However, WordPress’s own code often uses “sidebar” when it means “widget area,” because that code was written back when sidebars were the only kind of widget area.

Key Point: Widget Areas Go in Themes

Because a widget area is part of how your site will display—and not the data the site contains—it’s something to program in your theme rather than a plugin. That means you’ll be writing the PHP for your widget area into your theme’s functions.php.

Key Point: register_sidebar( $args )

The main function to create a WordPress widget area is simple: register_sidebar().

That function comes along with a lot of options, and the way you set these options is to create an array (by convention, generally named $args) that defines values for all these options. A very simple call to register_sidebar() would look like this:

$args = array(
    'name'          => 'Widgetized Sidebar',
    'id'            => "widgetized-sidebar",
register_sidebar( $args );

For a real widget area, the article gives a much fuller set of options for $args.

Key Point: Hooking into widgets_init

Your call to register_sidebar() needs to find its proper place in WordPress’s loading sequence, and it does this with WordPress’s hooks system. The action hook for, so the full code to register a sidebar would look as follows:

function my_theme_widgets_init() {
    $args = array(
        'name'          => 'Widgetized Sidebar',
        'id'            => "widgetized-sidebar",
    register_sidebar( $args );
add_action( 'widgets_init', 'my_theme_widgets_init' );

Key Point: Inserting the Registered Widget Area into Your Theme with dynamic_sidebar()

Once you’ve registered your widget area, you’ll need to put it “where it goes” in your theme—into your sidebar area, your footer, or what have you. The key function that does this is dynamic_sidebar(). Wrapped up in the proper checks that the widget area exists and has widgets in it, as well as some example HTML markup, that looks as follows:

<?php if ( is_active_sidebar( 'widgetized-sidebar' ) ) : ?>
    <div id="secondary" class="widget-area" role="complementary">
        <?php dynamic_sidebar( 'widgetized-sidebar' ); ?>
    </div><!-- #secondary -->
<?php endif; ?>

Now You Get WordPress Widgets!

Thanks for reading our first WPShout Course. We’re really excited about Courses as a method of covering complex WordPress topics that takes you from start to finish and helps your knowledge build on itself.

Sooo, how’d it work for widgets and widget areas? Did you manage to create your own WordPress widgets? We’d love to hear your thoughts and questions below

11 thoughts on “Creating WordPress Widgets: The Complete Guide”

  1. Pingback: Output Buffering in PHP: The Basics (and why it's great for shortcodes)

  2. Pingback: .

  3. Pingback: Happy Holidays! | WPShout

  4. Pingback: "What is WordPress?": What to Tell Your Clients | WPShout

  5. Very good article, this new “Course” feature is invaluable for new WordPress developers. There is a huge number of WP development tutorials around the web and on this site but, as you have correctly noted, they are not always easy to find. This new feature should help in that direction. Hope to see a course on database related stuff, with some good examples, e.g. creating user custom profiles, updating profiles and retrieving them for viewing etc.

    Thank you 🙂

    1. Belatedly: Thanks so much, Surja! That means a lot.

      We’ve noted your course request—we’ll let you know if we’re able to put something together on that topic!

  6. Pingback: How to Add Existing Taxonomies to WordPress Custom Post Types | WPShout

  7. Great detailed article. I need to define a widget that shows up only on the shopping cart page (Woocommerce). Currently I use a full width template for the cart page. How do I implement this widget area so it shows up only on the cart page and nowhere else on the site?

Leave a Reply

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

Or start the conversation in our Facebook group for WordPress professionals. Find answers, share tips, and get help from other WordPress experts. Join now (it’s free)!

Most Searched Articles

Best JavaScript Libraries and Frameworks: Try These 14 in 2024

In this post, we look at the best JavaScript libraries and frameworks to try out this year. Why? Well, with JavaScript being available in every web browser, this makes it the most accessible programming language of ...

25 Best Free WordPress Themes (Responsive, Mobile-Ready, Beautiful)

If you're looking for only the best free WordPress themes in the market for this year, then you're in the right place. We have more than enough such themes for you right ...

12 Best WordPress Hosting Providers of 2024 Compared and Tested

Looking for the best WordPress hosting that you can actually afford? We did the testing for you. Here are 10+ best hosts on the market ...

Handpicked Articles

How to Make a WordPress Website: Ultimate Guide for All Users – Beginners, Intermediate, Advanced

Many people wonder how to make a WordPress website. They’ve heard about WordPress, its incredible popularity, excellent features and designs, and now they want to join the pack and build a WordPress website of their own. So, where does one get ...

How to Start an Ecommerce Business: Ultimate Guide for 2024

Is this going to be the year you learn how to start an eCommerce business from scratch? You’re certainly in the right place! This guide will give you a roadmap to getting from 0 to a fully functional eCommerce business. ...