Title: WP_Customize_Setting::preview
Published: April 25, 2014
Last modified: May 20, 2026

---

# WP_Customize_Setting::preview(): bool

## In this article

 * [Description](https://developer.wordpress.org/reference/classes/WP_Customize_Setting/preview/?output_format=md#description)
 * [Return](https://developer.wordpress.org/reference/classes/WP_Customize_Setting/preview/?output_format=md#return)
 * [Source](https://developer.wordpress.org/reference/classes/WP_Customize_Setting/preview/?output_format=md#source)
 * [Hooks](https://developer.wordpress.org/reference/classes/WP_Customize_Setting/preview/?output_format=md#hooks)
 * [Related](https://developer.wordpress.org/reference/classes/WP_Customize_Setting/preview/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/classes/WP_Customize_Setting/preview/?output_format=md#changelog)

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

Add filters to supply the setting’s value when accessed.

## 󠀁[Description](https://developer.wordpress.org/reference/classes/WP_Customize_Setting/preview/?output_format=md#description)󠁿

If the setting already has a pre-existing value and there is no incoming post value
for the setting, then this method will short-circuit since there is no change to
preview.

## 󠀁[Return](https://developer.wordpress.org/reference/classes/WP_Customize_Setting/preview/?output_format=md#return)󠁿

 bool False when preview short-circuits due no change needing to be previewed.

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

    ```php
    public function preview() {
    	if ( ! isset( $this->_previewed_blog_id ) ) {
    		$this->_previewed_blog_id = get_current_blog_id();
    	}

    	// Prevent re-previewing an already-previewed setting.
    	if ( $this->is_previewed ) {
    		return true;
    	}

    	$id_base                 = $this->id_data['base'];
    	$is_multidimensional     = ! empty( $this->id_data['keys'] );
    	$multidimensional_filter = array( $this, '_multidimensional_preview_filter' );

    	/*
    	 * Check if the setting has a pre-existing value (an isset check),
    	 * and if doesn't have any incoming post value. If both checks are true,
    	 * then the preview short-circuits because there is nothing that needs
    	 * to be previewed.
    	 */
    	$undefined     = new stdClass();
    	$needs_preview = ( $undefined !== $this->post_value( $undefined ) );
    	$value         = null;

    	// Since no post value was defined, check if we have an initial value set.
    	if ( ! $needs_preview ) {
    		if ( $this->is_multidimensional_aggregated ) {
    			$root  = self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['root_value'];
    			$value = $this->multidimensional_get( $root, $this->id_data['keys'], $undefined );
    		} else {
    			$default       = $this->default;
    			$this->default = $undefined; // Temporarily set default to undefined so we can detect if existing value is set.
    			$value         = $this->value();
    			$this->default = $default;
    		}
    		$needs_preview = ( $undefined === $value ); // Because the default needs to be supplied.
    	}

    	// If the setting does not need previewing now, defer to when it has a value to preview.
    	if ( ! $needs_preview ) {
    		if ( ! has_action( "customize_post_value_set_{$this->id}", array( $this, 'preview' ) ) ) {
    			add_action( "customize_post_value_set_{$this->id}", array( $this, 'preview' ) );
    		}
    		return false;
    	}

    	switch ( $this->type ) {
    		case 'theme_mod':
    			if ( ! $is_multidimensional ) {
    				add_filter( "theme_mod_{$id_base}", array( $this, '_preview_filter' ) );
    			} else {
    				if ( empty( self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['previewed_instances'] ) ) {
    					// Only add this filter once for this ID base.
    					add_filter( "theme_mod_{$id_base}", $multidimensional_filter );
    				}
    				self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['previewed_instances'][ $this->id ] = $this;
    			}
    			break;
    		case 'option':
    			if ( ! $is_multidimensional ) {
    				add_filter( "pre_option_{$id_base}", array( $this, '_preview_filter' ) );
    			} else {
    				if ( empty( self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['previewed_instances'] ) ) {
    					// Only add these filters once for this ID base.
    					add_filter( "option_{$id_base}", $multidimensional_filter );
    					add_filter( "default_option_{$id_base}", $multidimensional_filter );
    				}
    				self::$aggregated_multidimensionals[ $this->type ][ $id_base ]['previewed_instances'][ $this->id ] = $this;
    			}
    			break;
    		default:
    			/**
    			 * Fires when the WP_Customize_Setting::preview() method is called for settings
    			 * not handled as theme_mods or options.
    			 *
    			 * The dynamic portion of the hook name, `$this->id`, refers to the setting ID.
    			 *
    			 * @since 3.4.0
    			 *
    			 * @param WP_Customize_Setting $setting WP_Customize_Setting instance.
    			 */
    			do_action( "customize_preview_{$this->id}", $this );

    			/**
    			 * Fires when the WP_Customize_Setting::preview() method is called for settings
    			 * not handled as theme_mods or options.
    			 *
    			 * The dynamic portion of the hook name, `$this->type`, refers to the setting type.
    			 *
    			 * @since 4.1.0
    			 *
    			 * @param WP_Customize_Setting $setting WP_Customize_Setting instance.
    			 */
    			do_action( "customize_preview_{$this->type}", $this );
    	}

    	$this->is_previewed = true;

    	return true;
    }
    ```

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

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

 [do_action( “customize_preview_{$this->id}”, WP_Customize_Setting $setting )](https://developer.wordpress.org/reference/hooks/customize_preview_this-id/)

Fires when the [WP_Customize_Setting::preview()](https://developer.wordpress.org/reference/classes/wp_customize_setting/preview/)
method is called for settings not handled as theme_mods or options.

 [do_action( “customize_preview_{$this->type}”, WP_Customize_Setting $setting )](https://developer.wordpress.org/reference/hooks/customize_preview_this-type/)

Fires when the [WP_Customize_Setting::preview()](https://developer.wordpress.org/reference/classes/wp_customize_setting/preview/)
method is called for settings not handled as theme_mods or options.

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

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

Checks if any action has been registered for a hook.

  | 
| [WP_Customize_Setting::multidimensional_get()](https://developer.wordpress.org/reference/classes/wp_customize_setting/multidimensional_get/)`wp-includes/class-wp-customize-setting.php` |

Will attempt to fetch a specific value from a multidimensional array.

  | 
| [WP_Customize_Setting::value()](https://developer.wordpress.org/reference/classes/wp_customize_setting/value/)`wp-includes/class-wp-customize-setting.php` |

Fetch the value of the setting.

  | 
| [WP_Customize_Setting::post_value()](https://developer.wordpress.org/reference/classes/wp_customize_setting/post_value/)`wp-includes/class-wp-customize-setting.php` |

Fetch and sanitize the $_POST value for the setting.

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

Retrieves the current site ID.

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

Adds a callback function to an action hook.

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

Adds a callback function to a filter hook.

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

Calls the callback functions that have been added to an action hook.

  |

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

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

| Version | Description | 
| [4.4.0](https://developer.wordpress.org/reference/since/4.4.0/) | Added boolean return value. | 
| [3.4.0](https://developer.wordpress.org/reference/since/3.4.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_setting%2Fpreview%2F)
before being able to contribute a note or feedback.