register_sidebar() WordPress Function

The register_sidebar() function is used to register sidebars in WordPress. A sidebar is a vertical column on the side of a web page that contains content such as text, images, or links. Sidebars are commonly used to display information that is not a part of the main content of the page. The register_sidebar() function takes two arguments: an ID and a name. The ID is used to identify the sidebar in the code. The name is used to identify the sidebar in the WordPress admin interface. After registering a sidebar, it can be displayed on a page using the dynamic_sidebar() function.

register_sidebar( array|string $args = array() ) #

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


Description

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()


Top ↑

Parameters

$args

(array|string)(Optional)Array or string of arguments for the sidebar being registered.

  • '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.
  • '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 is an opening list item element.
  • 'after_widget'
    (string) HTML content to append to each widget's HTML output when assigned to this sidebar. Default is a closing list item element.
  • 'before_title'
    (string) HTML content to prepend to the sidebar title when displayed. Default is an opening h2 element.
  • 'after_title'
    (string) HTML content to append to the sidebar title when displayed. Default is a 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 'dynamic_sidebar_before' action. Default empty string.
  • 'after_sidebar'
    (string) HTML content to append to the sidebar when displayed. Outputs before the 'dynamic_sidebar_after' action. Default empty string.
  • 'show_in_rest'
    (bool) Whether to show this sidebar publicly in the REST API. Defaults to only showing the sidebar to administrator users.

Default value: array()


Top ↑

Return

(string) Sidebar ID added to $wp_registered_sidebars global.


Top ↑

Source

File: 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'];
}


Top ↑

Changelog

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

The content displayed on this page has been created in part by processing WordPress source code files which are made available under the GPLv2 (or a later version) license by theĀ Free Software Foundation. In addition to this, the content includes user-written examples and information. All material is subject to review and curation by the WPPaste.com community.