Class: WP_Customize_Partial

Core Customizer class for implementing selective refresh partials.

Representation of a rendered region in the previewed page that gets selectively refreshed when an associated setting is changed. This class is analogous of WP_Customize_Control.


Name Type(s) Default Value Summary
component WP_Customize_Selective_Refresh Component.
id string Unique identifier for the partial.

If the partial is used to display a single setting, this would generally be the same as the associated setting's ID.

id_data array Parsed ID.
type string Type of this partial.
selector string The jQuery selector to find the container element for the partial.
settings array IDs for settings tied to the partial.
primary_setting string The ID for the setting that this partial is primarily responsible for rendering.

If not supplied, it will default to the ID of the first setting.

capability string Capability required to edit this partial.

Normally this is empty and the capability is derived from the capabilities of the associated $settings.

render_callback callable Render callback.
container_inclusive boolean Whether the container element is included in the partial, or if only the contents are rendered.
fallback_refresh boolean Whether to refresh the entire preview in case a partial cannot be refreshed.

A partial render is considered a failure if the render_callback returns false.


WP_Customize_Partial:: __construct( WP_Customize_Selective_Refresh $component, string $id, array $args = array() )

Constructor. Since 4.5.0.

Supplied $args override class property defaults.

If $args['settings'] is not defined, use the $id as the setting ID.


Name Type(s) Default Value Description
$component WP_Customize_Selective_Refresh

Customize Partial Refresh plugin instance.

$id string

Control ID.

$args array

{ Optional. Arguments to override class property defaults.

@type array|string $settings All settings IDs tied to the partial. If undefined, `$id` will be used.


WP_Customize_Partial:: check_capabilities( )

Checks if the user can refresh this partial. Since 4.5.0.

Returns false if the user cannot manipulate one of the associated settings, or if one of the associated settings does not exist.



False if user can't edit one of the related settings, or if one of the associated settings does not exist.

WP_Customize_Partial:: id_data( )

Retrieves parsed ID data for multidimensional setting. Since 4.5.0.



{ ID data for multidimensional partial.

@type string $base ID base.
@type array  $keys Keys for multidimensional array.


WP_Customize_Partial:: json( )

Retrieves the data to export to the client via JSON. Since 4.5.0.



Array of parameters passed to the JavaScript.

WP_Customize_Partial:: render( array $container_context = array() )

Renders the template partial involving the associated settings. Since 4.5.0.


Name Type(s) Default Value Description
$container_context array

Optional. Array of context data associated with the target container (placement). Default empty array.


string | array | false

The rendered partial as a string, raw data array (for client-side JS template), or false if no render applied.

WP_Customize_Partial:: render_callback( WP_Customize_Partial $partial, array $context = array() )

Default callback used when invoking WP_Customize_Control::render(). Since 4.5.0.

Note that this method may echo the partial or return the partial as a string or array, but not both. Output buffering is performed when this is called. Subclasses can override this with their specific logic, or they may provide an 'render_callback' argument to the constructor.

This method may return an HTML string for straight DOM injection, or it may return an array for supporting Partial JS subclasses to render by applying to client-side templating.


Name Type(s) Default Value Description
$partial WP_Customize_Partial


$context array



string | array | false

WordPress Developer Newsletter

Stay informed of new chapter releases, important WordPress API updates and more.