Title: retrieve_widgets
Published: April 25, 2014
Last modified: February 24, 2026

---

# retrieve_widgets( string|bool $theme_changed = false ): array

## In this article

 * [Description](https://developer.wordpress.org/reference/functions/retrieve_widgets/?output_format=md#description)
 * [Parameters](https://developer.wordpress.org/reference/functions/retrieve_widgets/?output_format=md#parameters)
 * [Return](https://developer.wordpress.org/reference/functions/retrieve_widgets/?output_format=md#return)
 * [Source](https://developer.wordpress.org/reference/functions/retrieve_widgets/?output_format=md#source)
 * [Related](https://developer.wordpress.org/reference/functions/retrieve_widgets/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/functions/retrieve_widgets/?output_format=md#changelog)

[ Back to top](https://developer.wordpress.org/reference/functions/retrieve_widgets/?output_format=md#wp--skip-link--target)

Validates and remaps any “orphaned” widgets to wp_inactive_widgets sidebar, and 
saves the widget settings. This has to run at least on each theme change.

## 󠀁[Description](https://developer.wordpress.org/reference/functions/retrieve_widgets/?output_format=md#description)󠁿

For example, let’s say theme A has a “footer” sidebar, and theme B doesn’t have 
one.
After switching from theme A to theme B, all the widgets previously assigned
to the footer would be inaccessible. This function detects this scenario, and moves
all the widgets previously assigned to the footer under wp_inactive_widgets.

Despite the word “retrieve” in the name, this function actually updates the database
and the global `$sidebars_widgets`. For that reason it should not be run on front
end, unless the `$theme_changed` value is ‘customize’ (to bypass the database write).

## 󠀁[Parameters](https://developer.wordpress.org/reference/functions/retrieve_widgets/?output_format=md#parameters)󠁿

 `$theme_changed`string|booloptional

Whether the theme was changed as a boolean. A value of `'customize'` defers updates
for the Customizer.

Default:`false`

## 󠀁[Return](https://developer.wordpress.org/reference/functions/retrieve_widgets/?output_format=md#return)󠁿

 array Updated sidebars widgets.

## 󠀁[Source](https://developer.wordpress.org/reference/functions/retrieve_widgets/?output_format=md#source)󠁿

    ```php
    function retrieve_widgets( $theme_changed = false ) {
    	global $wp_registered_sidebars, $sidebars_widgets, $wp_registered_widgets;

    	$registered_sidebars_keys = array_keys( $wp_registered_sidebars );
    	$registered_widgets_ids   = array_keys( $wp_registered_widgets );

    	if ( ! is_array( get_theme_mod( 'sidebars_widgets' ) ) ) {
    		if ( empty( $sidebars_widgets ) ) {
    			return array();
    		}

    		unset( $sidebars_widgets['array_version'] );

    		$sidebars_widgets_keys = array_keys( $sidebars_widgets );
    		sort( $sidebars_widgets_keys );
    		sort( $registered_sidebars_keys );

    		if ( $sidebars_widgets_keys === $registered_sidebars_keys ) {
    			$sidebars_widgets = _wp_remove_unregistered_widgets( $sidebars_widgets, $registered_widgets_ids );

    			return $sidebars_widgets;
    		}
    	}

    	// Discard invalid, theme-specific widgets from sidebars.
    	$sidebars_widgets = _wp_remove_unregistered_widgets( $sidebars_widgets, $registered_widgets_ids );
    	$sidebars_widgets = wp_map_sidebars_widgets( $sidebars_widgets );

    	// Replace non-array values inside the array with an empty array.
    	foreach ( $sidebars_widgets as $key => $value ) {
    		if ( ! is_array( $value ) ) {
    			$sidebars_widgets[ $key ] = array();
    		}
    	}

    	// Find hidden/lost multi-widget instances.
    	$shown_widgets = array_merge( ...array_values( $sidebars_widgets ) );
    	$lost_widgets  = array_diff( $registered_widgets_ids, $shown_widgets );

    	foreach ( $lost_widgets as $key => $widget_id ) {
    		$number = preg_replace( '/.+?-([0-9]+)$/', '$1', $widget_id );

    		// Only keep active and default widgets.
    		if ( is_numeric( $number ) && (int) $number < 2 ) {
    			unset( $lost_widgets[ $key ] );
    		}
    	}
    	$sidebars_widgets['wp_inactive_widgets'] = array_merge( $lost_widgets, (array) $sidebars_widgets['wp_inactive_widgets'] );

    	if ( 'customize' !== $theme_changed ) {
    		// Update the widgets settings in the database.
    		wp_set_sidebars_widgets( $sidebars_widgets );
    	}

    	return $sidebars_widgets;
    }
    ```

[View all references](https://developer.wordpress.org/reference/files/wp-includes/widgets.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/6.9.4/src/wp-includes/widgets.php#L1325)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-includes/widgets.php#L1325-L1380)

## 󠀁[Related](https://developer.wordpress.org/reference/functions/retrieve_widgets/?output_format=md#related)󠁿

| Uses | Description | 
| [_wp_remove_unregistered_widgets()](https://developer.wordpress.org/reference/functions/_wp_remove_unregistered_widgets/)`wp-includes/widgets.php` |

Compares a list of sidebars with their widgets against an allowed list.

  | 
| [wp_map_sidebars_widgets()](https://developer.wordpress.org/reference/functions/wp_map_sidebars_widgets/)`wp-includes/widgets.php` |

Compares a list of sidebars with their widgets against an allowed list.

  | 
| [get_theme_mod()](https://developer.wordpress.org/reference/functions/get_theme_mod/)`wp-includes/theme.php` |

Retrieves theme modification value for the active theme.

  | 
| [wp_set_sidebars_widgets()](https://developer.wordpress.org/reference/functions/wp_set_sidebars_widgets/)`wp-includes/widgets.php` |

Sets the sidebar widget option to update sidebars.

  |

| Used by | Description | 
| [WP_REST_Widgets_Controller::retrieve_widgets()](https://developer.wordpress.org/reference/classes/wp_rest_widgets_controller/retrieve_widgets/)`wp-includes/rest-api/endpoints/class-wp-rest-widgets-controller.php` |

Looks for “lost” widgets once per request.

  | 
| [WP_REST_Sidebars_Controller::retrieve_widgets()](https://developer.wordpress.org/reference/classes/wp_rest_sidebars_controller/retrieve_widgets/)`wp-includes/rest-api/endpoints/class-wp-rest-sidebars-controller.php` |

Looks for “lost” widgets once per request.

  | 
| [_wp_sidebars_changed()](https://developer.wordpress.org/reference/functions/_wp_sidebars_changed/)`wp-includes/widgets.php` |

Handles sidebars config after theme change.

  | 
| [WP_Customize_Widgets::override_sidebars_widgets_for_theme_switch()](https://developer.wordpress.org/reference/classes/wp_customize_widgets/override_sidebars_widgets_for_theme_switch/)`wp-includes/class-wp-customize-widgets.php` |

Override sidebars_widgets for theme switch.

  |

## 󠀁[Changelog](https://developer.wordpress.org/reference/functions/retrieve_widgets/?output_format=md#changelog)󠁿

| Version | Description | 
| [2.8.0](https://developer.wordpress.org/reference/since/2.8.0/) | Introduced. |

## User Contributed Notes

You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fretrieve_widgets%2F)
before being able to contribute a note or feedback.