wp_register_sidebar_widget( int|string $id, string $name, callable $output_callback, array $options = array(), mixed $params )
Register an instance of a widget.
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
-
$id
int|string Required -
Widget ID.
-
$name
string Required -
Widget display title.
-
$output_callback
callable Required -
Run when widget is called.
-
$options
array Optional -
An array of supplementary widget options for the instance.
classname
stringClass name for the widget's HTML container. Default is a shortened version of the output callback name.description
stringWidget description for display in the widget administration panel and/or theme.show_instance_in_rest
boolWhether to show the widget's instance settings in the REST API.
Only available for WP_Widget based widgets.
Default:
array()
-
$params
mixed Optional -
Optional additional parameters to pass to the callback function when it's called.
Source
File: wp-includes/widgets.php
.
View all references
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 ] );
return;
}
$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 ] );
return;
}
$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;
}
}
Hooks
-
do_action( 'wp_register_sidebar_widget',
array $widget ) -
Fires once for each registered widget.
Changelog
Version | Description |
---|---|
5.8.0 | Added show_instance_in_rest option. |
5.3.0 | Formalized the existing and already documented ...$params parameter by adding it to the function signature. |
2.2.0 | Introduced. |
User Contributed Notes
You must log in before being able to contribute a note or feedback.
Example
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.