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

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

Parameters

$argsarray|stringoptional
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:array()

Return

string Sidebar ID added to $wp_registered_sidebars global.

Source

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

Hooks

do_action( ‘register_sidebar’, array $sidebar )

Fires once a sidebar has been registered.

apply_filters( ‘register_sidebar_defaults’, array $defaults )

Filters the sidebar default arguments.

Changelog

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

User Contributed Notes

  1. Skip to note 7 content

    This example creates a sidebar named “Main Sidebar” with and before and after the title.

    /**
     * Add a sidebar.
     */
    function wpdocs_theme_slug_widgets_init() {
    	register_sidebar( array(
    		'name'          => __( 'Main Sidebar', 'textdomain' ),
    		'id'            => 'sidebar-1',
    		'description'   => __( 'Widgets in this area will be shown on all posts and pages.', 'textdomain' ),
    		'before_widget' => '<li id="%1$s" class="widget %2$s">',
    		'after_widget'  => '</li>',
    		'before_title'  => '<h2 class="widgettitle">',
    		'after_title'   => '</h2>',
    	) );
    }
    add_action( 'widgets_init', 'wpdocs_theme_slug_widgets_init' );
  2. Skip to note 9 content
    /* Better way to add multiple widgets areas */
    function widget_registration($name, $id, $description,$beforeWidget, $afterWidget, $beforeTitle, $afterTitle){
    	register_sidebar( array(
    		'name' => $name,
    		'id' => $id,
    		'description' => $description,
    		'before_widget' => $beforeWidget,
    		'after_widget' => $afterWidget,
    		'before_title' => $beforeTitle,
    		'after_title' => $afterTitle,
    	));
    }
    
    function multiple_widget_init(){
    	widget_registration('Footer widget 1', 'footer-sidebar-1', 'test', '', '', '', '');
    	widget_registration('Footer widget 2', 'footer-sidebar-2', 'test', '', '', '', '');
    	// ETC...
    }
    
    add_action('widgets_init', 'multiple_widget_init');
  3. Skip to note 11 content
    /* Add Multiple sidebar 
    */
    if ( function_exists('register_sidebar') ) {
    	$sidebar1 = array(
    		'before_widget' => '<div class="widget %2$s">',
    		'after_widget' => '</div>',
    		'before_title' => '<h2 class="widgettitle">',
    		'after_title' => '</h2>',        
    		'name'=>__( 'My sidebar 1', 'textdomain' ),	
    	);	
    	$sidebar2 = array(
    		'before_widget' => '<div class="widget %2$s">',
    		'after_widget' => '</div>',
    		'before_title' => '<h2 class="widgettitle">',
    		'after_title' => '</h2>',        
    		'name'=>__( 'My sidebar 2', 'textdomain' ),	
    	);
        $sidebar3 = array(
    		'before_widget' => '<div class="widget %2$s">',
    		'after_widget' => '</div>',
    		'before_title' => '<h2 class="widgettitle">',
    		'after_title' => '</h2>',        
    		'name'=>__( 'My sidebar 3', 'textdomain' ),	
    	);
        $sidebar4 = array(
    		'before_widget' => '<div class="widget %2$s">',
    		'after_widget' => '</div>',
    		'before_title' => '<h2 class="widgettitle">',
    		'after_title' => '</h2>',        
    		'name'=>__( 'My sidebar 4', 'textdomain' ),	
    	);
    	
    	register_sidebar($sidebar1);
    	register_sidebar($sidebar2);
        register_sidebar($sidebar3);
        register_sidebar($sidebar4);
    }
  4. Skip to note 12 content

    Note: when calling is_sidebar_active() or dynamic_sidebar(), the argument passed in these function is always sanitized via sanitize_title(). This function, amongst the other transforms, also lowercases the $index that is being passed.

    When using those two functions, you should remember to register the sidebar name in all lowercase and with a sanitize_title() compatible id, otherwise calling the widget area will always return false.

You must log in before being able to contribute a note or feedback.