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

Description

Parameters

$argsarray|stringoptional

Array or string of arguments for the sidebar being registered.Default: array()

• $namestringdefault: 'Sidebar $instance'

  The name or title of the sidebar displayed in the Widgets interface.

• $idstringdefault: 'sidebar-$instance'

  The unique identifier by which the sidebar will be called.

• $descriptionstringdefault: empty string

  Description of the sidebar, displayed in the Widgets interface.

• $classstringdefault: empty

  Extra CSS class to assign to the sidebar in the Widgets interface.

• $before_widgetstringdefault: is an opening list item element

  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.

• $after_widgetstringdefault: is a closing list item element

  HTML content to append to each widget's HTML output when assigned to this sidebar.

• $before_titlestringdefault: is an opening h2 element

  HTML content to prepend to the sidebar title when displayed.

• $after_titlestringdefault: is a closing h2 element

  HTML content to append to the sidebar title when displayed.

• $before_sidebarstringdefault: empty 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.

• $after_sidebarstringdefault: empty string

  HTML content to append to the sidebar when displayed. Outputs before the 'dynamic_sidebar_after' action.

• $show_in_restbool

  Whether to show this sidebar publicly in the REST API. Defaults to only showing the sidebar to administrator users.

Return

string

Sidebar ID added to $wp_registered_sidebars global.

Hooks fired · 2

2 hooks fire while register_sidebar() runs, in this order:

1. 1
   apply_filters( register_sidebar_defaults )filterline 300 (+31 into the body)

   Filters the sidebar default arguments.

2. 2
   do_action( register_sidebar )actionline 327 (+58 into the body)

   Fires once a sidebar has been registered.

Uses · 6

• __()Retrieves the translation of $text.
• wp_parse_args()Merges user defined arguments into defaults array.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• _doing_it_wrong()Marks something as being incorrectly called.
• add_theme_support()Registers theme support for a given feature.
• do_action()Calls the callback functions that have been added to an action hook.

Used by · 12

• register_sidebars()Creates multiple sidebars.
• twenty_twenty_one_widgets_init()Registers widget area.
• twentyeleven_widgets_init()Registers sidebars and widgetized areas.
• twentyfifteen_widgets_init()Registers widget area.
• twentyfourteen_widgets_init()Registers three Twenty Fourteen widget areas.
• twentynineteen_widgets_init()Registers widget area.
• twentyseventeen_widgets_init()Registers widget area.
• twentysixteen_widgets_init()Registers a widget area.
• twentyten_widgets_init()Registers widgetized areas, including two sidebars and four widget-ready columns in the footer.
• twentythirteen_widgets_init()Registers two widget areas.
• twentytwelve_widgets_init()Registers sidebars.
• twentytwenty_sidebar_registration()Registers widget areas.

Source

View on Trac ↗View on GitHub ↗

269function register_sidebar( $args = array() ) {270	global $wp_registered_sidebars;271 272	$i = count( $wp_registered_sidebars ) + 1;273 274	$id_is_empty = empty( $args['id'] );275 276	$defaults = array(277		/* translators: %d: Sidebar number. */278		'name'           => sprintf( __( 'Sidebar %d' ), $i ),279		'id'             => "sidebar-$i",280		'description'    => '',281		'class'          => '',282		'before_widget'  => '<li id="%1$s" class="widget %2$s">',283		'after_widget'   => "</li>\n",284		'before_title'   => '<h2 class="widgettitle">',285		'after_title'    => "</h2>\n",286		'before_sidebar' => '',287		'after_sidebar'  => '',288		'show_in_rest'   => false,289	);290 291	/**292	 * Filters the sidebar default arguments.293	 *294	 * @since 5.3.0295	 *296	 * @see register_sidebar()297	 *298	 * @param array $defaults The default sidebar arguments.299	 */300	$sidebar = wp_parse_args( $args, apply_filters( 'register_sidebar_defaults', $defaults ) );301 302	if ( $id_is_empty ) {303		_doing_it_wrong(304			__FUNCTION__,305			sprintf(306				/* translators: 1: The 'id' argument, 2: Sidebar name, 3: Recommended 'id' value. */307				__( '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.' ),308				'<code>id</code>',309				$sidebar['name'],310				$sidebar['id']311			),312			'4.2.0'313		);314	}315 316	$wp_registered_sidebars[ $sidebar['id'] ] = $sidebar;317 318	add_theme_support( 'widgets' );319 320	/**321	 * Fires once a sidebar has been registered.322	 *323	 * @since 3.0.0324	 *325	 * @param array $sidebar Parsed arguments for the registered sidebar.326	 */327	do_action( 'register_sidebar', $sidebar );328 329	return $sidebar['id'];330}

History

Introduced in 2.2.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.1.0 tag, from src/wp-includes/widgets.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.