register_sidebar() │ WP 2.2.0

Builds the definition for a single sidebar and returns the ID.

Accepts either a string or an array and then parses that against a set of default arguments for the new sidebar. WordPress will automatically generate a sidebar ID and name based on the current number of registered sidebars if those arguments are not included.

When allowing for automatic generation of the name and ID parameters, keep in mind that the incrementor for your sidebar can change over time depending on what other plugins and themes are installed.

If theme support for 'widgets' has not yet been added when this function is called, it will be automatically enabled through the use of add_theme_support()

Used By: register_sidebars()
Hooks from the function

Return

String. Sidebar ID added to $wp_registered_sidebars global.

Usage

register_sidebar( $args );
$args(array|string)

Array or string of arguments for the sidebar being registered.

Default: array()

  • name(string)
    The name or title of the sidebar displayed in the Widgets interface.
    Default: 'Sidebar $instance'

  • id(string)
    The unique identifier by which the sidebar will be called.
    Default: 'sidebar-$instance'

  • description(string)
    Description of the sidebar, displayed in the Widgets interface.
    Default: empty string

  • class(string)
    Extra CSS class to assign to the sidebar in the Widgets interface.
    Default: ''

  • before_widget(string)
    HTML content to prepend to each widget's HTML output when assigned to this sidebar. Receives the widget's ID attribute as %1$s and class name as %2$s.
    Default: an opening list item element

  • after_widget(string)
    HTML content to append to each widget's HTML output when assigned to this sidebar.
    Default: closing list item element

  • before_title(string)
    HTML content to prepend to the sidebar title when displayed.
    Default: an opening h2 element

  • after_title(string)
    HTML content to append to the sidebar title when displayed.
    Default: closing h2 element

  • before_sidebar(string)
    HTML content to prepend to the sidebar when displayed. Receives the $id argument as %1$s and $class as %2$s. Outputs after the {@see 'dynamic_sidebar_before'} action.
    Default: empty string

  • after_sidebar(string)
    HTML content to append to the sidebar when displayed. Outputs before the {@see 'dynamic_sidebar_after'} action.
    Default: empty string

  • show_in_rest(true|false)
    Whether to show this sidebar publicly in the REST API.
    Default: only showing the sidebar to administrator users

Examples

0

#1 Register widgets for the sidebar

The code below, will register a panel called "Right sidebar of the site". The panel name will be wrapped in <div class="title"> and </div> tags:

id parameter value must be in lowercase and no spaces!

add_action( 'widgets_init', 'register_my_widgets' );

function register_my_widgets(){

	register_sidebar( [
		'name' => 'The right sidebar of the site',
		'id' => 'right-sidebar',
		'description' => 'These widgets will be shown in the right column of the site',
		'before_title' => '<h2>',
		'after_title' => '</h2>'
	] );
}

After put this code into the theme functions.php file, a panel will appear in the admin-panel on the widgets page, where we can add widgets. In the template file, this panel is displayed with the function dynamic_sidebar():

<?php
if ( function_exists( 'dynamic_sidebar' ) ) {
	dynamic_sidebar( 'right-sidebar' );
}
?>
0

#2 Register a widget panel for the home page

Add the code to functions.php:

add_action( 'widgets_init', 'register_my_widgets' );

function register_my_widgets(){

	register_sidebar( array(
		'name' => 'Sidebar on home page',
		'id'   => 'homepage-sidebar',
		'description'   => 'Displayed as a sidebar only on the home page of the site.',
		'before_widget' => '<li id="%1$s" class="homepage-widget-block %2$s">',
		'after_widget'  => '</li>',
		'before_title'  => '<h2 class="widgettitle">',
		'after_title'   => '</h2>',
	) );
}

In the file home.php let's insert the panel output:

<div class="custom">
	<?php
	if ( function_exists('dynamic_sidebar') )
		dynamic_sidebar('homepage-sidebar');
	?>
</div>
0

#3 Add Multiple sidebar

There is a special function to do this: see register_sidebars().

Notes

  • Global. Array. $wp_registered_sidebars The registered sidebars.

Changelog

Since 2.2.0 Introduced.
Since 5.6.0 Added the before_sidebar and after_sidebar arguments.
Since 5.9.0 Added the show_in_rest argument.

register_sidebar() code WP 6.5.2

wp-includes/widgets.php 
function register_sidebar( $args = array() ) {
	global $wp_registered_sidebars;

	$i = count( $wp_registered_sidebars ) + 1;

	$id_is_empty = empty( $args['id'] );

	$defaults = array(
		/* translators: %d: Sidebar number. */
		'name'           => sprintf( __( 'Sidebar %d' ), $i ),
		'id'             => "sidebar-$i",
		'description'    => '',
		'class'          => '',
		'before_widget'  => '<li id="%1$s" class="widget %2$s">',
		'after_widget'   => "</li>\n",
		'before_title'   => '<h2 class="widgettitle">',
		'after_title'    => "</h2>\n",
		'before_sidebar' => '',
		'after_sidebar'  => '',
		'show_in_rest'   => false,
	);

	/**
	 * Filters the sidebar default arguments.
	 *
	 * @since 5.3.0
	 *
	 * @see register_sidebar()
	 *
	 * @param array $defaults The default sidebar arguments.
	 */
	$sidebar = wp_parse_args( $args, apply_filters( 'register_sidebar_defaults', $defaults ) );

	if ( $id_is_empty ) {
		_doing_it_wrong(
			__FUNCTION__,
			sprintf(
				/* translators: 1: The 'id' argument, 2: Sidebar name, 3: Recommended 'id' value. */
				__( 'No %1$s was set in the arguments array for the "%2$s" sidebar. Defaulting to "%3$s". Manually set the %1$s to "%3$s" to silence this notice and keep existing sidebar content.' ),
				'<code>id</code>',
				$sidebar['name'],
				$sidebar['id']
			),
			'4.2.0'
		);
	}

	$wp_registered_sidebars[ $sidebar['id'] ] = $sidebar;

	add_theme_support( 'widgets' );

	/**
	 * Fires once a sidebar has been registered.
	 *
	 * @since 3.0.0
	 *
	 * @param array $sidebar Parsed arguments for the registered sidebar.
	 */
	do_action( 'register_sidebar', $sidebar );

	return $sidebar['id'];
}

Sidebar (widgets)

Widgets (sidebars)

Main Functions