How to Register & Display Sidebars in WordPress

UPDATED ON APRIL 16, 2019
PUBLISHED ON NOVEMBER 14, 2013

Sidebar is a theme functionality introduced with WordPress Version 2.2. This is one of the best features in WordPress that gave a lot of flexibility in Theme and Dynamic Custom Site Development. Initially, the sidebar was used only as a vertical column provided by a theme for displaying information other than the main content of the web page. But now sidebar usages has been expanded dramatically. It can be any part of your WordPress site and it’s an excellent way to display information.

The term Sidebar refers to two different things in WordPress:

1. Dynamic sidebar: It is a dynamic widgetized area (container) where you can add single or multiple widgets from your WordPress Dashboard (Appearance => Widgets).
2. Sidebar template: It is a WordPress template which display the content in the sidebar.

Registering a Dynamic WordPress Sidebar

First you need to register your dynamic sidebar to use the sidebar functionality. This part is very important and always use proper code to register your sidebar.

Registering a sidebar or multiple sidebar is fairly simple stuff. Most common approach is to add the register_sidebar( $args ); function with widgets_init() action hook in your theme functions.php file. The code shown below is an example of how to properly register a sidebar in WordPress.

<?php
/**
 * Register Sidebar
 */
function textdomain_register_sidebars() {

	/* Register first sidebar name Primary Sidebar */
	register_sidebar(
		array(
			'name'			=> __( 'Primary Sidebar', 'textdomain' ),
			'id' 			=> 'sidebar-1',
			'description' => __( 'A short description of the sidebar.', 'textdomain' ),
			'before_widget' => '<section id="%1$s" class="widget %2$s">',
			'after_widget' => '</section>',
			'before_title' => '<h2 class="widget-title">',
			'after_title' => '</h2>'
		)
	);

	/* Register second sidebar name Secondary Sidebar */
	register_sidebar(
		array(
			'name'			=> __( 'Secondary Sidebar', 'textdomain' ),
			'id' 			=> 'sidebar-2',
			'description' => __( 'A short description of the sidebar.', 'textdomain' ),
			'before_widget' => '<section id="%1$s" class="widget %2$s">',
			'after_widget' => '</section>',
			'before_title' => '<h2 class="widget-title">',
			'after_title' => '</h2>'
		)
	);	

	/* Repeat register_sidebar() code for additional sidebars. */
}
add_action( 'widgets_init', 'textdomain_register_sidebars' );
?>

Register Sidebars code from Twenty Seventeen Default WordPress Theme functions.php file

/**
 * Register widget area.
 *
 * @link https://developer.wordpress.org/themes/functionality/sidebars/#registering-a-sidebar
 */
function twentyseventeen_widgets_init() {
	register_sidebar(
		array(
			'name'          => __( 'Blog Sidebar', 'twentyseventeen' ),
			'id'            => 'sidebar-1',
			'description'   => __( 'Add widgets here to appear in your sidebar on blog posts and archive pages.', 'twentyseventeen' ),
			'before_widget' => '<section id="%1$s" class="widget %2$s">',
			'after_widget'  => '</section>',
			'before_title'  => '<h2 class="widget-title">',
			'after_title'   => '</h2>',
		)
	);

	register_sidebar(
		array(
			'name'          => __( 'Footer 1', 'twentyseventeen' ),
			'id'            => 'sidebar-2',
			'description'   => __( 'Add widgets here to appear in your footer.', 'twentyseventeen' ),
			'before_widget' => '<section id="%1$s" class="widget %2$s">',
			'after_widget'  => '</section>',
			'before_title'  => '<h2 class="widget-title">',
			'after_title'   => '</h2>',
		)
	);

	register_sidebar(
		array(
			'name'          => __( 'Footer 2', 'twentyseventeen' ),
			'id'            => 'sidebar-3',
			'description'   => __( 'Add widgets here to appear in your footer.', 'twentyseventeen' ),
			'before_widget' => '<section id="%1$s" class="widget %2$s">',
			'after_widget'  => '</section>',
			'before_title'  => '<h2 class="widget-title">',
			'after_title'   => '</h2>',
		)
	);
}
add_action( 'widgets_init', 'twentyseventeen_widgets_init' );

Arguments for dynamic_sidebar()

The register_sidebar() function accepts a single parameter named $args. $args is an array of arguments that define how the sidebar and its widgets should be handled.

1. name: The name argument is the human-readable label for your sidebar used in the WordPress admin. Don’t make this name random and use proper name that you think best represents the name of your sidebar. It can be internationalized with __() function where the first parameter is the name and second parameter is theme textdomain.
2. id: The id argument is the most important argument you can set for your sidebar. This unique ID will be used to assign widgets to a specific sidebar, and to call sidebar in your template. Each ID should be unique to the sidebar and must be in lowercase with no spaces in between. By default, WordPress sets this to sidebar-$i (where $i is a count of the registered sidebars).
3. description: The description argument is the human-readable description for your sidebar used in the WordPress admin. It allows you to set a specific description for how the sidebar is used within your theme. This argument defaults to an empty string. It can be internationalized with __() function where the first parameter is the description and second parameter is theme textdomain.
4. before_widget: The before_widget argument is a wrapper HTML element for widgets assigned to the sidebar. This argument has a couple of things that you should always set with specific code so that plugins can properly use them, which is the id (%1$s) and class (%2$s) attributes.
5. after_widget: The after_widget argument is a closing wrapper HTML element for widgets assigned to the sidebar. You just need to close off the element you set for the before_widget argument.
6. before_title: Most widgets display a title if the user sets one. The before_title argument is the opening wrapper HTML element for the sidebar’s widget titles.
7. after_title: The after_title argument is to close the wrapper HTML element set in the before_title argument.

Displaying Dynamic Sidebars

After completing the process of registering sidebar, you will need to call dynamic_sidebar() function to display it in your WordPress theme. The dynamic_sidebar() function takes a single parameter of $index, which can either be the sidebar’s id or name argument that you have set while registering sidebar. The best and safer was to call sidebar with id argument.

The WordPress Twenty Seventeen theme uses the below code in sidebar.php file to display sidebar-1 sidebar. The following code uses a wrapper element so that the sidebar can be easily styled with CSS. Note dynamic_sidebar() can technically be called anywhere within your theme.

<aside id="secondary" class="widget-area" role="complementary" aria-label="<?php esc_attr_e( 'Blog Sidebar', 'twentyseventeen' ); ?>">
	<?php dynamic_sidebar( 'sidebar-1' ); ?>
</aside><!-- #secondary -->

Collapse sidebars without widgets

You can opt to collapse sidebar if the sidebar is inactive (No Widgets in the particular sidebar). For that, you need to use is_active_sidebar() conditional tag to check in the sidebar has any widgets assigned to it or not.

Like the dynamic_sidebar() function used to load the sidebar, is_active_sidebar() accepts a single parameter of $index, which should be the ID of the sidebar you want to check for active widgets.

The WordPress Twenty Seventeen theme uses the below code in sidebar.php file to check in the sidebar has any widgets assigned to it. It will display the sidebar-1 only if there is any active widget in it.

<?php 
if ( ! is_active_sidebar( 'sidebar-1' ) ) {
	return;
}
?>

<aside id="secondary" class="widget-area" role="complementary" aria-label="<?php esc_attr_e( 'Blog Sidebar', 'twentyseventeen' ); ?>">
	<?php dynamic_sidebar( 'sidebar-1' ); ?>
</aside><!-- #secondary -->

In the same way, Twenty Seventeen theme uses the below code in footer-widgets.php.php file to check in the footer sidebars has any widgets assigned to it. It will display the sidebar-2 and sidebar-3 only if there is any active widget in it.

<?php
if ( is_active_sidebar( 'sidebar-2' ) ||
	is_active_sidebar( 'sidebar-3' ) ) :
	?>

	<aside class="widget-area" role="complementary" aria-label="<?php esc_attr_e( 'Footer', 'twentyseventeen' ); ?>">
		<?php
		if ( is_active_sidebar( 'sidebar-2' ) ) {
			?>
			<div class="widget-column footer-widget-1">
				<?php dynamic_sidebar( 'sidebar-2' ); ?>
			</div>
			<?php
		}
		if ( is_active_sidebar( 'sidebar-3' ) ) {
			?>
			<div class="widget-column footer-widget-2">
				<?php dynamic_sidebar( 'sidebar-3' ); ?>
			</div>
		<?php } ?>
	</aside><!-- .widget-area -->

<?php endif; ?>

Displaying default sidebar content

Instead of collapse sidebar, you may opt to display default content when a user hasn’t assigned any widgets to a specific sidebar. To check if a dynamic sidebar has any widgets, you would use the is_active_sidebar() conditional tag.

With the below code, you can check if the sidebar-1 has widgets. If so, display the widgets. Else, display some custom content.

<?php 
if ( is_active_sidebar( 'sidebar-1' ) ) : ?>
	<aside id="secondary" class="widget-area" role="complementary" aria-label="<?php esc_attr_e( 'Blog Sidebar', 'twentyseventeen' ); ?>">
		<?php dynamic_sidebar( 'sidebar-1' ); ?>
	</aside><!-- #secondary -->
<?php 
else : ?>
	<!-- Create some custom HTML or call the_widget().  It's up to you. Here we have added one custom widget and three default widgets widgets -->
	<aside id="secondary" class="widget-area" role="complementary" aria-label="<?php esc_attr_e( 'Blog Sidebar', 'twentyseventeen' ); ?>">
		<section id="custom-widget-1" class="widget widget_custom">
			<h2 class="widget-title"><?php _e( 'This is Custom Widget Title', 'twentyseventeen' ); ?></h2>
			<div class="widget-content">
				<p>This is custom widget content</p>
			</div>
		</section>

		<?php 	
		the_widget( 'WP_Widget_Recent_Posts' );

		the_widget( 'WP_Widget_Categories' );

		the_widget( 'WP_Widget_Tag_Cloud' );
		?>
	</aside>
<?php endif; ?>

Sidebar Templates

Sidebar templates are typically a php file where the code for a dynamic sidebar are added. Most of the WordPress theme has a single sidebar template file called sidebar.php. But you have more template files. For example: Twenty Seventeen theme uses two sidebar template files called sidebar.php and footer-widgets.php, where dynamic sidebar sidebar-1 code is added in sidebar.php and sidebar-2 and sidebar-3 code is added in footer-widgets.php file.

Now, you can use get_sidebar( $name ); function or you can directly include the template file using get_template_part();. In Twenty Seventeen theme used the following functions to load both of the sidebar template.

<?php 
//Loading sidebar.php file
get_sidebar(); 
?>

<?php 
//Loading footer.php file
get_template_part( 'template-parts/footer/footer', 'widgets' ); ?>

Note

Sidebar templates don’t actually have to display dynamic sidebars. They can technically contain custom-coded content that displays anything. At the same time, you can display a dynamic sidebar in any template file you like.