{"id":6100,"date":"2026-02-13T18:24:27","date_gmt":"2026-02-13T23:24:27","guid":{"rendered":"https:\/\/chubes.net\/?documentation=selective-refresh"},"modified":"2026-03-13T03:28:12","modified_gmt":"2026-03-13T07:28:12","slug":"selective-refresh","status":"publish","type":"documentation","link":"https:\/\/chubes.net\/docs\/wordpress-core\/customize-classes\/selective-refresh\/","title":{"rendered":"Selective Refresh"},"content":{"rendered":"

Classes for implementing selective (partial) refresh in the Customizer preview.<\/p>

WP_Customize_Selective_Refresh<\/h2>

Core class for implementing selective refresh. Manages partial registration and handles Ajax rendering requests.<\/p>

Source:<\/strong> wp-includes\/customize\/class-wp-customize-selective-refresh.php<\/code>
\nSince:<\/strong> 4.5.0
\nFinal:<\/strong> Yes
\nAttributes:<\/strong> #[AllowDynamicProperties]<\/code><\/p>

Constants<\/h3>
Constant<\/th>Value<\/th>Description<\/th><\/tr><\/thead>
RENDER_QUERY_VAR<\/code><\/td>'wp_customize_render_partials'<\/code><\/td>POST query var used in partial render requests<\/td><\/tr><\/tbody><\/table><\/figure>

Properties<\/h3>
Property<\/th>Type<\/th>Visibility<\/th>Default<\/th>Since<\/th>Description<\/th><\/tr><\/thead>
$manager<\/code><\/td>WP_Customize_Manager<\/td>public<\/td>\u2014<\/td>4.5.0<\/td>Customize manager instance<\/td><\/tr>
$partials<\/code><\/td>WP_Customize_Partial[]<\/td>protected<\/td>array()<\/code><\/td>4.5.0<\/td>Registered partial instances<\/td><\/tr>
$triggered_errors<\/code><\/td>array<\/td>protected<\/td>array()<\/code><\/td>4.5.0<\/td>Log of errors during partial rendering<\/td><\/tr>
$current_partial_id<\/code><\/td>string|null<\/td>protected<\/td>\u2014<\/td>4.5.0<\/td>Currently-rendering partial ID<\/td><\/tr><\/tbody><\/table><\/figure>

Methods<\/h3>
Method<\/th>Visibility<\/th>Since<\/th>Description<\/th><\/tr><\/thead>
__construct( $manager )<\/code><\/td>public<\/td>4.5.0<\/td>Stores manager, requires class-wp-customize-partial.php<\/code>, hooks init_preview<\/code> to customize_preview_init<\/code>.<\/td><\/tr>
partials()<\/code><\/td>public<\/td>4.5.0<\/td>Returns all registered partials.<\/td><\/tr>
add_partial( $id, $args )<\/code><\/td>public<\/td>4.5.0<\/td>Adds a partial. Accepts WP_Customize_Partial<\/code> object or ID + args. Applies customize_dynamic_partial_args<\/code> and customize_dynamic_partial_class<\/code> filters when constructing from args.<\/td><\/tr>
get_partial( $id )<\/code><\/td>public<\/td>4.5.0<\/td>Returns partial by ID, or null<\/code>.<\/td><\/tr>
remove_partial( $id )<\/code><\/td>public<\/td>4.5.0<\/td>Removes a partial by ID.<\/td><\/tr>
init_preview()<\/code><\/td>public<\/td>4.5.0<\/td>Hooks handle_render_partials_request<\/code> to template_redirect<\/code> and enqueue_preview_scripts<\/code> to wp_enqueue_scripts<\/code>.<\/td><\/tr>
enqueue_preview_scripts()<\/code><\/td>public<\/td>4.5.0<\/td>Enqueues customize-selective-refresh<\/code> script and hooks export_preview_data<\/code> to wp_footer<\/code> at priority 1000.<\/td><\/tr>
export_preview_data()<\/code><\/td>public<\/td>4.5.0<\/td>Exports partials JSON, renderQueryVar<\/code>, and localized strings to JS via inline script _customizePartialRefreshExports<\/code>. Switches to user locale for l10n.<\/td><\/tr>
add_dynamic_partials( $partial_ids )<\/code><\/td>public<\/td>4.5.0<\/td>Registers partials dynamically. For each ID, applies customize_dynamic_partial_args<\/code> filter (must return non-false array) and customize_dynamic_partial_class<\/code> filter. Returns array of newly-added partials.<\/td><\/tr>
is_render_partials_request()<\/code><\/td>public<\/td>4.5.0<\/td>Returns true<\/code> if $_POST[RENDER_QUERY_VAR]<\/code> is set.<\/td><\/tr>
handle_error( $errno, $errstr, $errfile, $errline )<\/code><\/td>public<\/td>4.5.0<\/td>Error handler during rendering. Logs error with partial ID, number, string, file, and line. Always returns true<\/code>.<\/td><\/tr>
handle_render_partials_request()<\/code><\/td>public<\/td>4.5.0<\/td>Main Ajax handler. Validates customize preview, decodes $_POST['partials']<\/code> JSON, registers dynamic partials, renders each partial for its container contexts, and sends JSON response with contents<\/code>, errors<\/code> (if WP_DEBUG_DISPLAY<\/code>), and setting_validities<\/code>.<\/td><\/tr><\/tbody><\/table><\/figure>

Hooks<\/h3>
Hook<\/th>Type<\/th>Since<\/th>Description<\/th><\/tr><\/thead>
customize_dynamic_partial_args<\/code><\/td>filter<\/td>4.5.0<\/td>Filters dynamic partial constructor args. Must return non-false array for partial to be registered.<\/td><\/tr>
customize_dynamic_partial_class<\/code><\/td>filter<\/td>4.5.0<\/td>Filters the class used to construct partials. Default 'WP_Customize_Partial'<\/code>.<\/td><\/tr>
customize_render_partials_before<\/code><\/td>action<\/td>4.5.0<\/td>Fires immediately before partials are rendered. Plugins can enqueue scripts\/styles here.<\/td><\/tr>
customize_render_partials_after<\/code><\/td>action<\/td>4.5.0<\/td>Fires immediately after partials are rendered. Plugins can scrape footer scripts here.<\/td><\/tr>
customize_render_partials_response<\/code><\/td>filter<\/td>4.5.0<\/td>Filters the response array. Plugins can inject $scripts<\/code> and $styles<\/code> dependencies.<\/td><\/tr><\/tbody><\/table><\/figure>

Localized Strings (exported to JS)<\/h3>
Key<\/th>Text<\/th><\/tr><\/thead>
shiftClickToEdit<\/code><\/td>"Shift-click to edit this element."<\/td><\/tr>
clickEditMenu<\/code><\/td>"Click to edit this menu."<\/td><\/tr>
clickEditWidget<\/code><\/td>"Click to edit this widget."<\/td><\/tr>
clickEditTitle<\/code><\/td>"Click to edit the site title."<\/td><\/tr>
clickEditMisc<\/code><\/td>"Click to edit this element."<\/td><\/tr>
badDocumentWrite<\/code><\/td>"document.write() is forbidden"<\/td><\/tr><\/tbody><\/table><\/figure>

WP_Customize_Partial<\/h2>

Representation of a rendered region in the previewed page that gets selectively refreshed when an associated setting changes.<\/p>

Source:<\/strong> wp-includes\/customize\/class-wp-customize-partial.php<\/code>
\nSince:<\/strong> 4.5.0
\nAttributes:<\/strong> #[AllowDynamicProperties]<\/code><\/p>

Properties<\/h3>
Property<\/th>Type<\/th>Visibility<\/th>Default<\/th>Since<\/th>Description<\/th><\/tr><\/thead>
$component<\/code><\/td>WP_Customize_Selective_Refresh<\/td>public<\/td>\u2014<\/td>4.5.0<\/td>Parent selective refresh component<\/td><\/tr>
$id<\/code><\/td>string<\/td>public<\/td>\u2014<\/td>4.5.0<\/td>Unique identifier. Typically matches the associated setting ID.<\/td><\/tr>
$id_data<\/code><\/td>array<\/td>protected<\/td>\u2014<\/td>4.5.0<\/td>Parsed ID with base<\/code> and keys<\/code> for multidimensional settings<\/td><\/tr>
$type<\/code><\/td>string<\/td>public<\/td>'default'<\/code><\/td>4.5.0<\/td>Partial type<\/td><\/tr>
$selector<\/code><\/td>string<\/td>public<\/td>\u2014<\/td>4.5.0<\/td>jQuery selector to find the container element<\/td><\/tr>
$settings<\/code><\/td>string[]<\/td>public<\/td>\u2014<\/td>4.5.0<\/td>IDs for settings tied to this partial. Defaults to [$id]<\/code>.<\/td><\/tr>
$primary_setting<\/code><\/td>string<\/td>public<\/td>\u2014<\/td>4.5.0<\/td>ID of the primary setting. Defaults to first setting.<\/td><\/tr>
$capability<\/code><\/td>string<\/td>public<\/td>\u2014<\/td>4.5.0<\/td>Required capability. Empty = derived from settings.<\/td><\/tr>
$render_callback<\/code><\/td>callable<\/td>public<\/td>\u2014<\/td>4.5.0<\/td>Render callback. Called with ($partial, $container_context)<\/code>. Can echo or return string\/array, or return false<\/code> on error. Defaults to [$this, 'render_callback']<\/code>.<\/td><\/tr>
$container_inclusive<\/code><\/td>bool<\/td>public<\/td>false<\/code><\/td>4.5.0<\/td>Whether the container element is included in the partial<\/td><\/tr>
$fallback_refresh<\/code><\/td>bool<\/td>public<\/td>true<\/code><\/td>4.5.0<\/td>Whether to do a full refresh if partial render fails<\/td><\/tr><\/tbody><\/table><\/figure>

Methods<\/h3>
Method<\/th>Visibility<\/th>Since<\/th>Description<\/th><\/tr><\/thead>
__construct( $component, $id, $args )<\/code><\/td>public<\/td>4.5.0<\/td>Accepts args matching property names. Parses ID into id_data<\/code>. Defaults render_callback<\/code> to $this->render_callback()<\/code>. Normalizes $settings<\/code> to array; defaults to [$id]<\/code>. Sets $primary_setting<\/code> to first setting if empty.<\/td><\/tr>
id_data()<\/code><\/td>public final<\/td>4.5.0<\/td>Returns parsed $id_data<\/code> array with base<\/code> and keys<\/code>.<\/td><\/tr>
render( $container_context )<\/code><\/td>public final<\/td>4.5.0<\/td>Calls $render_callback<\/code>, captures output buffer. Warns if callback both echoes and returns. Applies customize_partial_render<\/code> and customize_partial_render_{$partial->id}<\/code> filters. Returns string, array, or false<\/code>.<\/td><\/tr>
render_callback( $partial, $context )<\/code><\/td>public<\/td>4.5.0<\/td>Default callback \u2014 returns false<\/code> (no render). Subclasses override this.<\/td><\/tr>
json()<\/code><\/td>public<\/td>4.5.0<\/td>Returns array with settings<\/code>, primarySetting<\/code>, selector<\/code>, type<\/code>, fallbackRefresh<\/code>, containerInclusive<\/code>.<\/td><\/tr>
check_capabilities()<\/code><\/td>public final<\/td>4.5.0<\/td>Returns false<\/code> if user lacks $capability<\/code> or if any associated setting fails check_capabilities()<\/code>.<\/td><\/tr><\/tbody><\/table><\/figure>

Hooks<\/h3>
Hook<\/th>Type<\/th>Since<\/th>Description<\/th><\/tr><\/thead>
customize_partial_render<\/code><\/td>filter<\/td>4.5.0<\/td>Filters partial rendering result. Params: $rendered<\/code>, $partial<\/code>, $container_context<\/code>.<\/td><\/tr>
customize_partial_render_{$partial->id}<\/code><\/td>filter<\/td>4.5.0<\/td>Filters partial rendering for a specific partial ID. Same params.<\/td><\/tr><\/tbody><\/table><\/figure>","protected":false},"excerpt":{"rendered":"

Classes for implementing selective (partial) refresh in the Customizer preview. WP_Customize_Selective_Refresh Core class for implementing selective refresh. Manages partial registration and handles Ajax rendering requests. Source: wp-includes\/customize\/class-wp-customize-selective-refresh.php Since: 4.5.0 Final:…<\/p>\n","protected":false},"featured_media":0,"template":"","meta":{"footnotes":""},"tags":[],"project":[756],"project_type":[749],"class_list":["post-6100","documentation","type-documentation","status-publish","hentry","project-customize-classes","project_type-wordpress-reference"],"project_info":{"id":589,"name":"WordPress Core","slug":"wordpress-core"},"project_type_info":{"id":749,"name":"WordPress Reference","slug":"wordpress-reference"},"_links":{"self":[{"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/documentation\/6100","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/documentation"}],"about":[{"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/types\/documentation"}],"version-history":[{"count":2,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/documentation\/6100\/revisions"}],"predecessor-version":[{"id":7322,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/documentation\/6100\/revisions\/7322"}],"wp:attachment":[{"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/media?parent=6100"}],"wp:term":[{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/tags?post=6100"},{"taxonomy":"project","embeddable":true,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/project?post=6100"},{"taxonomy":"project_type","embeddable":true,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/project_type?post=6100"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}