Plugins Plugin hub Backup SEO Caching Security Forms WooCommerce Images Best backup plugins
Hosting Hosting directory Shared Managed Cloud India
Themes & builders Compare Rank Math vs Yoast
Tools All tools Hosting finder Plugin stack builder Cost calculator Salt generator Theme detector Who is hosting this? Speed test Headline analyzer robots.txt generator Redirect generator Uptime calculator Blog name generator
Best lists Best backup plugins Deals
Guides All guides Speed up WordPress Choose hosting Back up WordPress
How we test

Developer · Guide

How to Register a Widget Area

How to Register a Widget Area

Short answer

To register a widget area, hook a function to widgets_init and call register_sidebar() inside it with a name, a fixed id, a description, and the HTML wrappers for widgets and titles. Show the area in your theme template with dynamic_sidebar() using the same id, wrapped in an is_active_sidebar() check so empty areas print nothing. Always set a fixed id, since an auto-built id can change when other plugins add areas.

Key takeaways

  • register_sidebar() defines one widget area and returns its id as a string.
  • Hook registration to widgets_init, which fires at init with priority 1.
  • Always set a fixed id, since an auto-built id can change over time.
  • Show the area with dynamic_sidebar(), guarded by is_active_sidebar().
  • register_sidebars() makes several areas at once, with %d in the name.

What is a widget area in WordPress?

A widget area is a named slot in your theme where you or your users can place blocks and widgets.

It is also called a sidebar, even when it sits in a footer or below the content. The theme declares the slot, and the dashboard shows it as a place to add content.

A footer area might hold a search box, a short text block, and a list of recent posts. Make WordPress Support states that a sidebar in WordPress is a widget-ready area used to show information that is not part of the main content (checked November 2026).

Developer.WordPress.org states that register_sidebar() builds the definition for a single sidebar and returns its ID (checked November 2026).

That ID is the link between the code that declares the area and the template that shows it. Give each area a clear ID, such as footer-1, so the template can call it by name.

Widget areas differ from menus. A menu holds links, while a widget area holds blocks of any kind. A guide on block themes vs classic themes explains where widget areas fit in each theme type.

When should you register a new widget area?

Register a new widget area when a theme needs a slot that its current areas do not cover.

A theme with one sidebar and one footer area may need a second footer area for a shop page, or a narrow area beside single posts.

Each new area gives site owners a place to add content without editing theme files. Add areas only where the template will show them, since an area with no template call never appears on the site.

Check the theme first. Many themes already ship with 3 to 5 areas, such as a main sidebar and 3 footer areas. Open Appearance → Widgets in the dashboard and count the areas listed there.

If the area you need is already there, use it instead of writing code.

A new area fits a plugin too. A plugin that adds a booking form might register its own area so site owners can place the form where they want it. Keep the area name plain, such as “Booking Sidebar”, so users grasp its job at a glance.

What does register_sidebar() do?

register_sidebar() tells WordPress about one widget area and stores its settings for the dashboard and the front of the site.

Developer.WordPress.org states that the function accepts either a string or an array, and then parses it against a set of default arguments for the new sidebar (checked November 2026).

You will pass an array in almost every case, since the array form is clear and easy to read.

The function was introduced in WordPress 2.2.0, as its changelog states (checked November 2026).

That long history means the function works in every theme type that still uses sidebars, and its parameter names have stayed stable for years. The source code for the function lives in wp-includes/widgets.php in the WordPress codebase, as shown on GitHub (checked November 2026).

Developer.WordPress.org also states that if theme support for widgets has not been added when the function runs, WordPress adds it for you through add_theme_support() (checked November 2026).

You do not need a separate call to turn widget support on before you register an area.

How do you register a widget area with code?

Register a widget area by hooking a function to widgets_init and calling register_sidebar() inside it.

Developer.WordPress.org lists widgets_init as the hook used to register sidebars, and states that it fires at init with priority 1 (checked November 2026).

That early timing matters: the areas must exist before the dashboard and the theme try to list them.

Here is a short, working example based on the official docs:

function acme_widgets_init() {
    register_sidebar(
        array(
            'name'          => 'Footer Area',
            'id'            => 'footer-1',
            'description'   => 'Widgets in this area will be shown in the footer.',
            'before_widget' => '<' . 'div id="%1$s" class="widget %2$s">',
            'after_widget'  => '<' . '/div>',
            'before_title'  => '<' . 'h2 class="widgettitle">',
            'after_title'   => '<' . '/h2>',
        )
    );
}
add_action( 'widgets_init', 'acme_widgets_init' );

Put this code in the theme's functions.php file, or in a small custom plugin when the area belongs to a plugin.

A guide on theme vs plugin in WordPress helps you pick the right home for the code. Use a child theme when you add the area to a theme you did not write, so an update does not wipe it out.

What do the register_sidebar() parameters control?

The parameters of register_sidebar() set the name, ID, and HTML that wraps each widget in the area.

Developer.WordPress.org lists these parameters for the function (checked November 2026).

The name shows in the Widgets screen, and the id is the unique name the template uses to call the area. The description also shows in the Widgets screen, so write one line that states where the area appears.

The wrapper parameters set the HTML around each widget. The before_widget value runs before each widget, and after_widget runs after it. The before_title and after_title values wrap the widget title.

Developer.WordPress.org states that before_widget takes the widget ID as %1$s and the class name as %2$s (checked November 2026). Keep those two placeholders in your markup, since WordPress fills them in for each widget.

The defaults show what happens when you leave a value out. Developer.WordPress.org states that the default before_widget is an opening list item, the default after_widget is a closing list item, and the default title tags are an opening and closing h2 (checked November 2026).

Set your own wrappers when your theme needs div tags instead of list tags.

Two newer parameters cover extra cases. Developer.WordPress.org states that before_sidebar and after_sidebar were added in WordPress 5.6.0, and show_in_rest was added in WordPress 5.9.0 (checked November 2026).

The show_in_rest value decides whether the area shows in the REST API, and it defaults to false, so only admins see it there unless you set it true.

How do you show the widget area on the site?

Show the widget area by calling dynamic_sidebar() with the area ID in the theme template where it should appear.

The official docs show the standard pattern: wrap the call in a check with is_active_sidebar(), so the template prints nothing when the area is empty (checked November 2026). That check keeps empty markup off the page when no widgets are set.

Here is the pattern from the official docs:

<?php if ( is_active_sidebar( 'footer-1' ) ) : ?>
    <?php echo '<' . 'div id="footer-widgets">'; ?>
    <?php dynamic_sidebar( 'footer-1' ); ?>
    <?php echo '<' . '/div>'; ?>
<?php endif; ?>

Place this code in the template file for the spot you want, such as footer.php for a footer area or sidebar.php for a side area. The ID in the call must match the id you set in register_sidebar() exactly, including dashes and numbers.

If the area shows nothing, check three things in order. First, confirm the ID matches. Second, confirm the template file you edited is the one your theme loads for that page.

Third, open Appearance → Widgets and confirm at least one block sits in the area. A guide on fixing widgets that do not show walks through more causes when these three checks pass.

How do you add several widget areas at once?

Add several areas at once with register_sidebars(), which runs register_sidebar() once per area.

Developer.WordPress.org states that register_sidebars() creates multiple sidebars, and that its first parameter is the number of sidebars to make, with a default of 1 (checked November 2026).

Pass 3 as the number and one shared array of settings to make 3 areas that share the same wrappers.

Include a %d placeholder in the name when you make more than one area. Developer.WordPress.org states that for register_sidebars(), you should include %d in the name as a placeholder for the number, since the function passes each name through sprintf() (checked November 2026).

A name such as “Footer Area %d” becomes “Footer Area 1”, “Footer Area 2”, and “Footer Area 3”.

Set the id with care when you use this shortcut. Developer.WordPress.org states that a supplied id gets “-2”, “-3”, and so on added when it meets an area that already uses it (checked November 2026).

Give each area its own base ID, such as footer-1, footer-2, and footer-3, when you need exact IDs for your templates.

For most themes, 3 separate register_sidebar() calls read better than one register_sidebars() call. Use the plural form only when the areas truly share every setting except their number.

How do you check that the widget area works?

Check the area in the dashboard first, then on the live site.

Open Appearance → Widgets in the dashboard. Your new area should appear by the name you set, with the description under it. Drag a block into it, such as a paragraph block with a short test line, and save.

If the area is missing, your hook or your file is wrong: confirm the code sits in the active theme's functions.php or in an active plugin, and that the hook is widgets_init.

WordPress.org states that widgets can be added, removed, and rearranged on Appearance → Widgets in the dashboard (checked November 2026).

Next, open the page where the area should show. The test line should appear in that spot on the page. If it does not, confirm the template call uses the same ID and sits in the template for that page.

A guide on how to use block patterns in WordPress shows how saved blocks can fill a new area fast once the area itself works.

Remove the test block when the check passes, and add the real blocks for that area. Check the page on a phone screen too, since a footer area that looks fine on a desktop can stack in an odd order on a narrow screen.

What mistakes should you avoid?

Avoid registering the area on the wrong hook, because the area will not appear.

widgets_init is the hook for sidebars, as the WordPress action list states (checked November 2026). Code hooked to init or after_setup_theme may run at the wrong time, so the area can vanish from the dashboard or from the front of the site.

Avoid leaving the id out of the call. Developer.WordPress.org states that WordPress will build an ID and name from the count of registered sidebars when you omit them, and that the number can change as other plugins and themes add their own areas (checked November 2026).

A changing ID breaks the template call and can move widgets to a new area after an update. Always set a fixed, plain ID.

Avoid wrapping widgets in markup that breaks your theme. A before_widget value of an opening li tag inside a div container gives invalid HTML, and a missing %1$s placeholder gives every widget the same ID. Match the wrappers to the container in your template, and keep the placeholders in place.

ParameterWhat it setsDefault when left out
nameName shown in the Widgets screen“Sidebar” plus a number
idUnique ID used by dynamic_sidebar()“sidebar-” plus a number
descriptionNote shown in the Widgets screenEmpty
before_widgetHTML before each widgetOpening li tag
after_widgetHTML after each widgetClosing li tag
before_titleHTML before each widget titleOpening h2 tag
after_titleHTML after each widget titleClosing h2 tag
show_in_restShows the area in the REST APIFalse
Note: set a fixed id for every area you register, since an auto-built id can change when other plugins add areas.

Frequently asked questions

Where do I put the register_sidebar() code?

Put it in the theme functions.php file when the area belongs to a theme, or in a small custom plugin when it belongs to a plugin. Use a child theme when you add the area to a theme you did not write, so an update does not wipe it out. The code must run on the widgets_init hook, since that hook fires before the dashboard and the theme list the areas. Check Appearance → Widgets after you save.

Why does my widget area not show in the dashboard?

Check three things in order. First, confirm the code sits in the active theme functions.php file or in an active plugin. Second, confirm the hook is widgets_init, since other hooks run at the wrong time. Third, confirm the theme supports widgets by looking for Appearance → Widgets in the dashboard. If the menu item is missing, the theme may not support widget areas at all.

Can I add a widget area to a block theme?

Widget areas are built for classic themes. If your theme is a block theme, build the sidebar or footer with blocks in the Site Editor instead, since that is where block themes place such content. The register_sidebar() function still works in classic themes, and its areas show under Appearance → Widgets. Check which theme type you run before you write the code, so you build the right thing.

What happens if two areas share the same id?

WordPress adds a number to the id, such as -2 or -3, when it meets an area that already uses it. That changes the id your template calls, so the area may stop showing or show the wrong widgets. Give each area its own base id, such as footer-1, footer-2, and footer-3, when you need exact ids. Check the Widgets screen after you add a second area with a like name.

How many widget areas should a theme have?

Most themes ship with 3 to 5 areas, such as a main sidebar and 3 footer areas. Add a new area only where the template will show it, since an area with no template call never appears on the site. A shop page or a single post layout may need one extra area, but a dozen areas only clutter the Widgets screen. Count the areas under Appearance → Widgets before you add one.

Sources

  1. register_sidebar() Developer.WordPress.org
  2. register_sidebars() Developer.WordPress.org
  3. Action Reference - Common APIs Handbook Developer.WordPress.org
  4. Manage WordPress widgets WordPress.org
  5. Posts Make WordPress Support
  6. register_sidebar() source in wp-includes/widgets.php WordPress

Is your product missing, or something out of date?

Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.

About the editors

WPLegible editors

Researched from the primary sources listed above and checked against our editorial rules. About the site · How we test