WP_Customize_Selective_Refresh::add_partial( WP_Customize_Partial|string $id, array $args = array() ): WP_Customize_Partial

Adds a partial.


Top ↑

See also

Top ↑


$id WP_Customize_Partial|string Required
Customize Partial object, or Partial ID.
$args array Optional
Array of properties for the new Partials object.
See WP_Customize_Partial::__construct() for information on accepted arguments.
More Arguments from WP_Customize_Partial::__construct( ... $args ) Array of properties for the new Partials object.
  • type string
    Type of the partial to be created.
  • selector string
    The jQuery selector to find the container element for the partial, that is, a partial's placement.
  • settings string[]
    IDs for settings tied to the partial. If undefined, $id will be used.
  • 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.
    Callback is called with one argument, the instance of WP_Customize_Partial.
    The callback can either echo the partial or return the partial as a string, or return false if error.
  • container_inclusive bool
    Whether the container element is included in the partial, or if only the contents are rendered.
  • fallback_refresh bool
    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.

Default: array()

Top ↑


WP_Customize_Partial The instance of the partial that was added.

Top ↑


File: wp-includes/customize/class-wp-customize-selective-refresh.php. View all references

public function add_partial( $id, $args = array() ) {
	if ( $id instanceof WP_Customize_Partial ) {
		$partial = $id;
	} else {
		$class = 'WP_Customize_Partial';

		/** This filter is documented in wp-includes/customize/class-wp-customize-selective-refresh.php */
		$args = apply_filters( 'customize_dynamic_partial_args', $args, $id );

		/** This filter is documented in wp-includes/customize/class-wp-customize-selective-refresh.php */
		$class = apply_filters( 'customize_dynamic_partial_class', $class, $id, $args );

		$partial = new $class( $this, $id, $args );

	$this->partials[ $partial->id ] = $partial;
	return $partial;

Top ↑


Top ↑


Version Description
4.5.0 Introduced.

Top ↑

User Contributed Notes

  1. Skip to note 1 content
    Contributed by alejosky

    In case you wonder why the pencil icon is not showing in your theme (and maybe the “Shift-click to edit this element.” title does), it might be because you chose an “illegal” container selector to place it in. E.g:

    /* THIS WON'T WORK! */
    $wp_customize->selective_refresh->add_partial( 'second_logo', array(
    	'selector' => '.second-logo img' // img is an "illegal container selector"
    ) );

    If you look into customize-selective-refresh.js you will find that the “illegal” selectors are

    createEditShortcutForPlacement: function( placement ) {
    var //...
    illegalContainerSelector = 'area, audio, base, bdi, bdo, br, button, canvas, col, colgroup, command, datalist, embed, head, hr, html, iframe, img, input, keygen, label, link, map, math, menu, meta, noscript, object, optgroup, option, param, progress, rp, rt, ruby, script, select, source, style, svg, table, tbody, textarea, tfoot, thead, title, tr, track, video, wbr';

    In other words, you need to be sure that whatever element you point to as the container for the pencil icon is not one of those (not an image, not a hr, etc).

You must log in before being able to contribute a note or feedback.