wp_register_sidebar_widget( int|string $id, string $name, callable $output_callback, array $options = array(), mixed $params )

Register an instance of a widget.

Description Description

The default widget option is ‘classname’ that can be overridden.

The function can also be used to un-register widgets when $output_callback parameter is an empty string.

Parameters Parameters


(int|string) (Required) Widget ID.


(string) (Required) Widget display title.


(callable) (Required) Run when widget is called.


(array) (Optional) An array of supplementary widget options for the instance.

  • 'classname'
    (string) Class name for the widget's HTML container. Default is a shortened version of the output callback name.
  • 'description'
    (string) Widget description for display in the widget administration panel and/or theme.

Default value: array()


(mixed) (Optional) additional parameters to pass to the callback function when it's called.

Top ↑

Source Source

File: wp-includes/widgets.php

function wp_register_sidebar_widget( $id, $name, $output_callback, $options = array(), ...$params ) {
	global $wp_registered_widgets, $wp_registered_widget_controls, $wp_registered_widget_updates, $_wp_deprecated_widgets_callbacks;

	$id = strtolower( $id );

	if ( empty( $output_callback ) ) {
		unset( $wp_registered_widgets[ $id ] );

	$id_base = _get_widget_id_base( $id );
	if ( in_array( $output_callback, $_wp_deprecated_widgets_callbacks, true ) && ! is_callable( $output_callback ) ) {
		unset( $wp_registered_widget_controls[ $id ] );
		unset( $wp_registered_widget_updates[ $id_base ] );

	$defaults = array( 'classname' => $output_callback );
	$options  = wp_parse_args( $options, $defaults );
	$widget   = array(
		'name'     => $name,
		'id'       => $id,
		'callback' => $output_callback,
		'params'   => $params,
	$widget   = array_merge( $widget, $options );

	if ( is_callable( $output_callback ) && ( ! isset( $wp_registered_widgets[ $id ] ) || did_action( 'widgets_init' ) ) ) {

		 * Fires once for each registered widget.
		 * @since 3.0.0
		 * @param array $widget An array of default widget arguments.
		do_action( 'wp_register_sidebar_widget', $widget );
		$wp_registered_widgets[ $id ] = $widget;

Top ↑

Changelog Changelog

Version Description
5.3.0 Formalized the existing and already documented ...$params parameter by adding it to the function signature.
2.2.0 Introduced.

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    Contributed by Codex

    The following code will create a widget called “Wpdocs Widget” which will become available in the WordPress Administrative Panels. The widget can then be dragged to an available sidebar for display.

    Note that this widget can only be used once in exactly 1 of the sidebars. For recursive widgets (widgets you can add to multiple times and add to multiple sidebars) please see the Register Widget function.

    	'wpdocs_widget_1',		// wpdocs unique widget id
    	'Wpdocs Widget',		// widget name
    	'wpdocs_widget_display',	// callback function
    	array(				// options
    		'description' => 'Description of what the widget does'
     * Display the wpdocs widget
    function wpdocs_widget_display($args) {
       echo $args['before_widget'];
       echo $args['before_title'] . 'The Wpdocs Widget' .  $args['after_title'];
       echo $args['after_widget'];
       // Print some HTML for the widget to display here.
       echo __( 'Wpdocs Widget Test', 'textdomain' );

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