Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Class Reference/WP Customize Widgets

Role of WP_Customize_Widgets

WP_Customize_Widgets is WordPress' class for implementing widget management via the Theme Customization API for WordPress 3.9 and newer.

This live preview and management of widgets via the Customizer serves as a secondary option to the traditional widget management workflow already in place.


WordPress instantiates the class via WP_Customize_Manager and works by adding a new Customizer section for each of the active sidebars visible in the Customizer preview.

Methods and Properties


WP_Customize_Manager instance.
(array) All id_bases for widgets defined in core.


get_post_value( $name, $default = null )
Get an unslashed post value or return a default.
Set up widget addition previews.
Since the widgets get registered on 'widgets_init' before the Customizer settings are set up on 'customize_register', we have to filter the options similarly to how the setting previewer will filter the options later.
prepreview_added_sidebars_widgets( $sidebars_widgets )
Ensure that newly-added widgets will appear in the widgets_sidebars.
prepreview_added_widget_instance( $value = false )
Ensure newly-added widgets have empty instances so they will be recognized.
Remove pre-preview filters.
Override sidebars_widgets for theme switch.
filter_customize_value_old_sidebars_widgets_data( $old_sidebars_widgets )
Filter old_sidebars_widgets_data customizer setting.
filter_option_sidebars_widgets_for_theme_switch( $sidebars_widgets )
Filter sidebars_widgets option for theme switch.
Make sure all widgets get loaded into the Customizer.
Ensure widgets are available for all types of previews.
Register customizer settings and controls for all sidebars and widgets.
get_setting_id( $widget_id )
Convert a widget_id into its corresponding customizer setting ID (option name).
is_wide_widget( $widget_id )
Determine whether the widget is considered "wide".
parse_widget_id( $widget_id )
Convert a widget ID into its id_base and number components.
parse_widget_setting_id( $setting_id )
Convert a widget setting ID (option path) to its id_base and number components.
Print styles.
Print scripts.
Enqueue scripts.
Render the widget form control templates into the DOM.
Print footer scripts.
get_setting_args( $id, $overrides = array() )
Get common arguments to supply when constructing a Customizer setting.
sanitize_sidebar_widgets( $widget_ids )
Make sure that sidebar widget arrays only ever contain widget IDS. Used as the 'sanitize_callback' for each $sidebars_widgets setting.
Build up an index of all available widgets for use in Backbone models.
get_widget_control( $args )
Get the widget control markup.
Add hooks for the customizer preview.
preview_sidebars_widgets( $sidebars_widgets )
When previewing, make sure the proper previewing widgets are used.
Enqueue scripts for the Customizer preview.
Insert default style for highlighted widget at early point so theme stylesheet can override.
At the very end of the page, at the very end of the wp_footer, communicate the sidebars that appeared on the page.
tally_rendered_widgets( $widget )
Keep track of the widgets that were rendered.
tally_sidebars_via_is_active_sidebar_calls( $is_active, $sidebar_id )
Tally the sidebars rendered via is_active_sidebar().
tally_sidebars_via_dynamic_sidebar_calls( $has_widgets, $sidebar_id )
Tally the sidebars rendered via dynamic_sidebar().
sanitize_widget_instance( $value )
Sanitize a widget instance.
sanitize_widget_js_instance( $value )
Convert widget instance into JSON-representable format.
sanitize_sidebar_widgets_js_instance( $widget_ids )
Strip out widget IDs for widgets which are no longer registered.
call_widget_update( $widget_id )
Find and invoke the widget update and control callbacks.
Update widget settings asynchronously.
capture_filter_pre_update_option( $new_value, $option_name, $old_value )
Pre-filter captured option values before updating.
capture_filter_pre_get_option( $value )
Pre-filter captured option values before retrieving.


  • customizer_widgets_section_args
  • is_wide_widget_in_customizer
  • widget_customizer_setting_args

Source File

WP_Customize_Widgets is located in wp-includes/class-wp-customize-widgets.php.


See also index of Class Reference and index of Function Reference.