Title: WP_Customize_Widgets::customize_register
Published: April 25, 2014
Last modified: April 28, 2025

---

# WP_Customize_Widgets::customize_register()

## In this article

 * [Source](https://developer.wordpress.org/reference/classes/wp_customize_widgets/customize_register/?output_format=md#source)
 * [Hooks](https://developer.wordpress.org/reference/classes/wp_customize_widgets/customize_register/?output_format=md#hooks)
 * [Related](https://developer.wordpress.org/reference/classes/wp_customize_widgets/customize_register/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/classes/wp_customize_widgets/customize_register/?output_format=md#changelog)

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

Registers Customizer settings and controls for all sidebars and widgets.

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

    ```php
    public function customize_register() {
    	global $wp_registered_widgets, $wp_registered_widget_controls, $wp_registered_sidebars;

    	$use_widgets_block_editor = wp_use_widgets_block_editor();

    	add_filter( 'sidebars_widgets', array( $this, 'preview_sidebars_widgets' ), 1 );

    	$sidebars_widgets = array_merge(
    		array( 'wp_inactive_widgets' => array() ),
    		array_fill_keys( array_keys( $wp_registered_sidebars ), array() ),
    		wp_get_sidebars_widgets()
    	);

    	$new_setting_ids = array();

    	/*
    	 * Register a setting for all widgets, including those which are active,
    	 * inactive, and orphaned since a widget may get suppressed from a sidebar
    	 * via a plugin (like Widget Visibility).
    	 */
    	foreach ( array_keys( $wp_registered_widgets ) as $widget_id ) {
    		$setting_id   = $this->get_setting_id( $widget_id );
    		$setting_args = $this->get_setting_args( $setting_id );
    		if ( ! $this->manager->get_setting( $setting_id ) ) {
    			$this->manager->add_setting( $setting_id, $setting_args );
    		}
    		$new_setting_ids[] = $setting_id;
    	}

    	/*
    	 * Add a setting which will be supplied for the theme's sidebars_widgets
    	 * theme_mod when the theme is switched.
    	 */
    	if ( ! $this->manager->is_theme_active() ) {
    		$setting_id   = 'old_sidebars_widgets_data';
    		$setting_args = $this->get_setting_args(
    			$setting_id,
    			array(
    				'type'  => 'global_variable',
    				'dirty' => true,
    			)
    		);
    		$this->manager->add_setting( $setting_id, $setting_args );
    	}

    	$this->manager->add_panel(
    		'widgets',
    		array(
    			'type'                     => 'widgets',
    			'title'                    => __( 'Widgets' ),
    			'description'              => __( 'Widgets are independent sections of content that can be placed into widgetized areas provided by your theme (commonly called sidebars).' ),
    			'priority'                 => 110,
    			'active_callback'          => array( $this, 'is_panel_active' ),
    			'auto_expand_sole_section' => true,
    			'theme_supports'           => 'widgets',
    		)
    	);

    	foreach ( $sidebars_widgets as $sidebar_id => $sidebar_widget_ids ) {
    		if ( empty( $sidebar_widget_ids ) ) {
    			$sidebar_widget_ids = array();
    		}

    		$is_registered_sidebar = is_registered_sidebar( $sidebar_id );
    		$is_inactive_widgets   = ( 'wp_inactive_widgets' === $sidebar_id );
    		$is_active_sidebar     = ( $is_registered_sidebar && ! $is_inactive_widgets );

    		// Add setting for managing the sidebar's widgets.
    		if ( $is_registered_sidebar || $is_inactive_widgets ) {
    			$setting_id   = sprintf( 'sidebars_widgets[%s]', $sidebar_id );
    			$setting_args = $this->get_setting_args( $setting_id );
    			if ( ! $this->manager->get_setting( $setting_id ) ) {
    				if ( ! $this->manager->is_theme_active() ) {
    					$setting_args['dirty'] = true;
    				}
    				$this->manager->add_setting( $setting_id, $setting_args );
    			}
    			$new_setting_ids[] = $setting_id;

    			// Add section to contain controls.
    			$section_id = sprintf( 'sidebar-widgets-%s', $sidebar_id );
    			if ( $is_active_sidebar ) {

    				$section_args = array(
    					'title'      => $wp_registered_sidebars[ $sidebar_id ]['name'],
    					'priority'   => array_search( $sidebar_id, array_keys( $wp_registered_sidebars ), true ),
    					'panel'      => 'widgets',
    					'sidebar_id' => $sidebar_id,
    				);

    				if ( $use_widgets_block_editor ) {
    					$section_args['description'] = '';
    				} else {
    					$section_args['description'] = $wp_registered_sidebars[ $sidebar_id ]['description'];
    				}

    				/**
    				 * Filters Customizer widget section arguments for a given sidebar.
    				 *
    				 * @since 3.9.0
    				 *
    				 * @param array      $section_args Array of Customizer widget section arguments.
    				 * @param string     $section_id   Customizer section ID.
    				 * @param int|string $sidebar_id   Sidebar ID.
    				 */
    				$section_args = apply_filters( 'customizer_widgets_section_args', $section_args, $section_id, $sidebar_id );

    				$section = new WP_Customize_Sidebar_Section( $this->manager, $section_id, $section_args );
    				$this->manager->add_section( $section );

    				if ( $use_widgets_block_editor ) {
    					$control = new WP_Sidebar_Block_Editor_Control(
    						$this->manager,
    						$setting_id,
    						array(
    							'section'     => $section_id,
    							'sidebar_id'  => $sidebar_id,
    							'label'       => $section_args['title'],
    							'description' => $section_args['description'],
    						)
    					);
    				} else {
    					$control = new WP_Widget_Area_Customize_Control(
    						$this->manager,
    						$setting_id,
    						array(
    							'section'    => $section_id,
    							'sidebar_id' => $sidebar_id,
    							'priority'   => count( $sidebar_widget_ids ), // place 'Add Widget' and 'Reorder' buttons at end.
    						)
    					);
    				}

    				$this->manager->add_control( $control );

    				$new_setting_ids[] = $setting_id;
    			}
    		}

    		if ( ! $use_widgets_block_editor ) {
    			// Add a control for each active widget (located in a sidebar).
    			foreach ( $sidebar_widget_ids as $i => $widget_id ) {

    				// Skip widgets that may have gone away due to a plugin being deactivated.
    				if ( ! $is_active_sidebar || ! isset( $wp_registered_widgets[ $widget_id ] ) ) {
    					continue;
    				}

    				$registered_widget = $wp_registered_widgets[ $widget_id ];
    				$setting_id        = $this->get_setting_id( $widget_id );
    				$id_base           = $wp_registered_widget_controls[ $widget_id ]['id_base'];

    				$control = new WP_Widget_Form_Customize_Control(
    					$this->manager,
    					$setting_id,
    					array(
    						'label'          => $registered_widget['name'],
    						'section'        => $section_id,
    						'sidebar_id'     => $sidebar_id,
    						'widget_id'      => $widget_id,
    						'widget_id_base' => $id_base,
    						'priority'       => $i,
    						'width'          => $wp_registered_widget_controls[ $widget_id ]['width'],
    						'height'         => $wp_registered_widget_controls[ $widget_id ]['height'],
    						'is_wide'        => $this->is_wide_widget( $widget_id ),
    					)
    				);
    				$this->manager->add_control( $control );
    			}
    		}
    	}

    	if ( $this->manager->settings_previewed() ) {
    		foreach ( $new_setting_ids as $new_setting_id ) {
    			$this->manager->get_setting( $new_setting_id )->preview();
    		}
    	}
    }
    ```

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

## 󠀁[Hooks](https://developer.wordpress.org/reference/classes/wp_customize_widgets/customize_register/?output_format=md#hooks)󠁿

 [apply_filters( ‘customizer_widgets_section_args’, array $section_args, string $section_id, int|string $sidebar_id )](https://developer.wordpress.org/reference/hooks/customizer_widgets_section_args/)

Filters Customizer widget section arguments for a given sidebar.

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

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

Determines whether or not to use the block editor to manage widgets.

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

Checks if a sidebar is registered.

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

Retrieves the full list of sidebars and their widget instance IDs.

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

Retrieves common arguments to supply when constructing a Customizer setting.

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

Converts a widget_id into its corresponding Customizer setting ID (option name).

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

Determines whether the widget is considered “wide”.

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

Retrieves the translation of $text.

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

Adds a callback function to a filter hook.

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

Calls the callback functions that have been added to a filter hook.

  |

[Show 4 more](https://developer.wordpress.org/reference/classes/wp_customize_widgets/customize_register/?output_format=md#)
[Show less](https://developer.wordpress.org/reference/classes/wp_customize_widgets/customize_register/?output_format=md#)

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

Ensures widgets are available for all types of previews.

  |

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

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

## User Contributed Notes

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