How to register sidebars and add widget areas to WordPress themes

Every WordPress theme comes with at least one sidebar or widget area. Sometimes that’s not enough for certain projects. Sooner or later a developer will have to add more widget areas and place them in custom positions inside a WP theme. In this tutorial we’ll show you how to register sidebars and add widget areas to WordPress themes.

Required knowledge for this tutorial

Learning how to add widget areas to WordPress themes requires previous good knowledge of HTML and CSS. Basic experience in editing WordPress template PHP files would also come handy.

Pro Tip: If your version of WordPress doesn’t use syntax highlighting in it’s code editor, it would be helpful to activate this feature. Learn how to highligt code in our Syntax highlighting in WordPress tutorial.

Difference between WordPress widget areas and sidebars

Technically, there is no difference between a widget area and a dynamic sidebar in WordPress. From the visual aspect, widget areas can be positioned anywhere within the template. The sidebar is just a vertical widget area on the left or the right side of the content.

In the early days of WordPress, templates had only one sidebar to add widgets. Since that time until today, the function to register any widget area in WordPress is still called register_sidebar().

Common positioning of custom widget areas and sidebars in WordPress themes

Introduction to register_sidebar() and dynamic_sidebar() functions

The process of adding widget areas to WordPress themes consists of two main steps. Firstly you have to register your custom widget area in theme’s functions.php file. The new widget area or sidebar is registered using the register_sidebar() function. As a sub step after registering the widget area you can populate it with widgets in your WP Dashboard Widgets section.

The second step is displaying the widget area on your site’s front-end. It is done by embedding the widget area into your site’s template using the dynamic_sidebar() function. The function is added to the template file which contains the site section where you want to display the widget area. For example, to add a widget area to your site header, you add the dynamic_sidebar() function to the theme’s header.php file. With this step completed, your custom sidebar or widget area shows up on the front-end. As a sub step, you’ll probably want to style it up with some CSS.

1. Use register_sidebar() function to register sidebars and widget areas

As we mentioned before, the first step to add widget areas to WordPress themes is registering it in the Theme functions file. At this point we presume you are editing a child-theme. Direct editing of the active theme could result with loosing all your custom modifications when updating the theme. Be careful about it.

In our example, we’ll add a custom widget area to our site’s header. Open the functions.php file inside the Theme Editor and scroll to the bottom of it. To register the widget area, add the following code and save the changes:

function custom_header_widgetarea() {
  
    register_sidebar(
        array(
            'id'      => 'header-widgetarea',
            'name'    => __( 'Custom Header Widgetarea' ),
        )
    );
    
}

add_action( 'widgets_init', 'custom_header_widgetarea' );

In the code above we named our function custom_header_widgetarea. You can replace it with your custom name (one no-space string) in the first and last line of the example code. Furthermore, you can replace ’name’ and ’id’ parameter values with your own. Make sure you use a no-spaces string for the ’id’ parameter. We’ll use the ’id’ parameter in the next step, when embedding the widget area into the template file.

Now you can go into your WordPress dashboard Appearance/Widgets section and populate it with widgets you want to display. You will notice the new custom widget area is named according to what you defined in the ’name’ parameter of the register_sidebar() function.

2. Use dynamic_sidebar() function to display sidebars and widget areas

In this step we’ll to add widget areas to WordPress theme files using the dynamic_sidebar() function. In our example we’re adding our widget area to our site’s header. We’ll position it after all the other header elements (branding, navigation, etc..).

In the Theme editor, we’ll open the header.php template file and locate the closing </header> tag. We’ll add the dynamic_sidebar() function just under it, to display the widget area exactly between the site header and content sections. Here’s the code example we’re gona use to display our custom widget area:

<section id=”header-widgets”>
<ul><?php dynamic_sidebar( 'header-widgetarea' ); ?></ul>
</section>

We positioned our widget area inside a <section> block named header-widgets. You can also use <div> elements to wrap the widget area and change it’s id value as you like. Additionally, we wrapped the dynamic_sidebar() with <ul> elements, because by default WordPress will display the widgets as list elements <li>. In some cases WordPress will automatically add quotation marks to the <section> id. If you notice that happening, remove the quotation marks from your <section> id.

To display the widget area we’ve used the dynamic_sidebar() function with the id parameter previously defined in the register_sidebar() function. Make sure your id parameter defined when registering the widget area corresponds to the one inside the dynamic_sidebar() function.

If you’ve done everything correctly, your widgets will appear in the area between your header and site content. All you have to do now is apply some CSS styles to make it all look good visually.

In the same way you can display your widget area in any other part of your site. Just edit the corresponding template file. For example, edit footer.php to display widgets in the footer, single.php to put widgets inside a single post template or category.php to display the widgets only when browsing post categories.

More parameters to use when adding custom widget areas and sidebars

In the example above we used the most basic code and mandatory parameters to register and display a widget area. Now that you understand the process of registering sidebars (widget areas) and displaying them on your website, we’ll expand the code with additional useful parameters.

Previously, we already used and described the ’name’ and ’id’ parameters. Now, we’re gonna add the ’description’ parameter, which displays the widget area description inside the Appearance/Widgets dashboard panel. Furthermore, we’ll add the ’before_widget’ and ’after_widget’ parameters to define the HTML elements wrapping each widget. Here you can use HTML block elements such as <div>, <aside> or <ul><li>. You can also add ids and classes to those elements for easier targeting when styling the widgets later. We suggest to add id=”%1$s” class=”widget %2$s” to those elements. Those will display each widget name for easier CSS targeting. Finally, we’ll add the ’before_title’ and ’after_title’ parameters which will define the HTML elements wrapping widget titles.

Here’s how the widget area register function looks now, tweak it to your needs:

function custom_header_widgetarea() {
  
    register_sidebar(
        array(
            'id'            => 'header-widgetarea',
            'name'          => __( 'Custom Header Widgetarea' ),
            'description'   => __( 'Widgets positioned between header and content.' ),
            'before_widget' => '
',
            'after_widget'  => '
',
            'before_title'  => '
',
            'after_title'   => '
',
        )
    );
    
}

add_action( 'widgets_init', 'custom_header_widgetarea' );

Now, we’ll also modify a bit our dynamic_sidebar() function that displays the widget area inside the theme. We’ll add a query that checks if the widget area is populated with any widgets. In case there are no widgets, the widget area section won’t be displayed. That’s useful in case the widget area has some styles applied which would be visible even if there are no widgets to show (background color, padding, margins…).

Example of code that displays the widget area only if populated with widgets:

<?php if ( is_active_sidebar( 'header-widgetarea' ) ) : ?>
<section id=”header-widgets”>
<?php dynamic_sidebar( 'header-widgetarea' ); ?>
</section>
<?php endif; ?>

Note: In some cases WordPress will automatically add quotation marks to the <section> id. If you notice that happening, remove the quotation marks from your <section> id.

Expand your knowledge on WordPress sidebars and adding widget areas

To learn more about WordPress sidebars and widget areas read the Sidebars topic inside the WordPress.org Theme handbook.