register_sidebars() │ WP 2.2.0

Creates a specified number of widget areas (sidebars) and adds them to the system so that they can later be displayed using dynamic_sidebar().

The function is created for the convenient creation of multiple widget panels at once, so that the same parameters do not need to be passed to register_sidebar().

Must be used on the hook widgets_init.

Use register_sidebar() when you need to create only one panel.

Uses: register_sidebar()

No Hooks.

Returns

null. Does not return anything.

Usage template

$args = array(
	'name'          => 'Sidebar %d',
	'id'            => "sidebar",
	'before_widget' => '<li id="%1$s" class="widget %2$s">',
	'after_widget'  => '</li>',
	'before_title'  => '<h2 class="widgettitle">',
	'after_title'   => '</h2>'
);
register_sidebars( 2, $args );

Usage

register_sidebars( $number, $args );
$number(int)
How many panels to create, the number is specified.
Default: 1
$args(string/array)

Parameters for the created widget panels.

Parameters can be specified as an associative array or as a string.

  • name - The name of the panel. The names of the created panels must be different. If you are registering more than one sidebar, include the marker %d in the value of name — WordPress will substitute the ordinal number ("Sidebar 1", "Sidebar 2", etc.).

    In the absence of a unique id, the engine will automatically add a suffix -2, -3, etc., to avoid conflict.

    Default 'Sidebar %d'.

  • id - The identifier of the panel. An integer will automatically be added to each subsequent panel after the first. For example, if we create 3 panels and specify "sidebar" in id, we will get: "Sidebar", "Sidebar-2", "Sidebar-3".

  • description - The description of the panel. When creating multiple sidebars at once, this parameter does not make sense and is empty by default.

  • before_widget - HTML that will be placed before each widget in the panel.

  • after_widget - HTML that will be placed after each widget in the panel.

  • before_title - HTML that will be placed before each widget title in the panel.

  • after_title - HTML that will be placed after each widget title in the panel.

You can also specify parameters from register_sidebar().

Default: default

Examples

0

#1 Single panel registration

Analogue of register_sidebar():

register_sidebars( 1, [
	'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>',
] );

id parameter value must be in lowercase and no spaces!

0

#2 Registration of two panels

This example shows how to register 2 panels named "Foobar 1", "Foobar 2", "Foobar 3":

register_sidebars( 3, [
	'name' => 'Foobar %d',
	'id'   => 'right-sidebar',

	'description'  => 'These widgets will be shown in the right column of the site',
	'before_title' => '<h2>',
	'after_title'  => '</h2>'
] );

id parameter will changed automatically, the suffix will be added: right-sidebar, right-sidebar-2, right-sidebar-3

0

#3 Create 2 panels and put the title of each widget in the <h1> tag: 

register_sidebars( 2, [
	'before_title' => '<h1>',
	'after_title'  => '</h1>',
] );

The same, only we specify the parameters as a string:

register_sidebars( 2, "before_title=<h1>&after_title=</h1>" )

Notes

  • See: register_sidebar() The second parameter is documented by register_sidebar() and is the same here.
  • Global. Array. $wp_registered_sidebars The new sidebars are stored in this array by sidebar ID.

Changelog

Since 2.2.0 Introduced.

register_sidebars() code WP 6.9.1

wp-includes/widgets.php 
function register_sidebars( $number = 1, $args = array() ) {
	global $wp_registered_sidebars;
	$number = (int) $number;

	if ( is_string( $args ) ) {
		parse_str( $args, $args );
	}

	for ( $i = 1; $i <= $number; $i++ ) {
		$_args = $args;

		if ( $number > 1 ) {
			if ( isset( $args['name'] ) ) {
				$_args['name'] = sprintf( $args['name'], $i );
			} else {
				/* translators: %d: Sidebar number. */
				$_args['name'] = sprintf( __( 'Sidebar %d' ), $i );
			}
		} else {
			$_args['name'] = isset( $args['name'] ) ? $args['name'] : __( 'Sidebar' );
		}

		/*
		 * Custom specified ID's are suffixed if they exist already.
		 * Automatically generated sidebar names need to be suffixed regardless starting at -0.
		 */
		if ( isset( $args['id'] ) ) {
			$_args['id'] = $args['id'];
			$n           = 2; // Start at -2 for conflicting custom IDs.
			while ( is_registered_sidebar( $_args['id'] ) ) {
				$_args['id'] = $args['id'] . '-' . $n++;
			}
		} else {
			$n = count( $wp_registered_sidebars );
			do {
				$_args['id'] = 'sidebar-' . ++$n;
			} while ( is_registered_sidebar( $_args['id'] ) );
		}
		register_sidebar( $_args );
	}
}

Sidebar (widgets)

Widgets (sidebars)