wp_unregister_sidebar_widget() │ WP 2.2.0

Unregisters (removes) a widget by its ID.

  • This function also removes a widget from the Appearance -> Widgets panel if you use it in the theme functions.php file.

  • You can find out the ID of the widget in its id attribute in the Widgets panel. For example, a widget with ID your_widget_1 will have id="widget-17_your_widget_1" attribute. And a block of some other widget with, for example, with ID my_widget will have id="widget-18_my_widget" attribute.
Uses: wp_unregister_widget_control(), wp_register_sidebar_widget()
Hooks from the function

Return

null. Nothing.

Usage

wp_unregister_sidebar_widget( $id );
$id(int/string) (required)
Widget ID which was specified when registering a widget with wp_register_sidebar_widget().

Examples

#1 Disable (unregister) a specific widget on all is_category() pages

Suppose we have registered my_widget widget in functions.php file using wp_register_sidebar_widget() function:

function my_widget_display(){
	// Widget output
}
wp_register_sidebar_widget(
	'my_widget',          // The widget ID
	'My widget',          // The tidget title
	'my_widget_display',  // The widget callback
);

Then we have added this widget to the right-sidebar. This sidebar is called in sidebar.php:

<ul id="sidebar">
	<?php dynamic_sidebar( 'right-sidebar' ); ?>
</ul>

Now, to disable my_widget on all categories pages, we need to add the following code before displaying the sidebar:

<?php wp_unregister_sidebar_widget( 'my_widget' ); ?>

<ul id="sidebar">
	<?php dynamic_sidebar( 'right-sidebar' ); ?>
</ul>

Changelog

Since 2.2.0 Introduced.

Code of wp_unregister_sidebar_widget() WP 5.9.3

wp-includes/widgets.php 
function wp_unregister_sidebar_widget( $id ) {

	/**
	 * Fires just before a widget is removed from a sidebar.
	 *
	 * @since 3.0.0
	 *
	 * @param int|string $id The widget ID.
	 */
	do_action( 'wp_unregister_sidebar_widget', $id );

	wp_register_sidebar_widget( $id, '', '' );
	wp_unregister_widget_control( $id );
}

Sidebar (widgets)

Widgets (sidebars)