Documentation

Namespace: customize

wp. customize

Expose the API publicly on window.wp.customize
Source:

Classes

BackgroundControl
BackgroundPositionControl
CodeEditorControl
ColorControl
Control
CroppedImageControl
DateTimeControl
Element
HeaderControl
ImageControl
Loader
MediaControl
Messenger
Notification
Notifications
OuterSection
OverlayNotification
Panel
Preview
Previewer
PreviewFrame
PreviewLinkControl
Section
Setting
SiteIconControl
ThemeControl
ThemesPanel
ThemesSection
UploadControl
Value
Values
Container
LockedNotification

Namespaces

HeaderTool
Menus
navMenusPreview
selectiveRefresh
utils
Widgets
widgetsPreview

Members

<protected, static> _lastSavedRevision :number

Last revision that was saved.
Type:
  • number
Since:
  • 4.7.0
Source:

<protected, static> _latestRevision :number

Current change count.
Type:
  • number
Since:
  • 4.7.0
Source:

<protected, static> _latestSettingRevisions :object

Latest revisions associated with the updated setting.
Type:
  • object
Since:
  • 4.7.0
Source:

<static> control :function

Collection of all registered controls.
Type:
  • function
Since:
  • 3.4.0
Source:
Examples

Loop over all registered controls.

wp.customize.control.each( function( control ) { ... } );

Getting `background_color` control instance.

control = wp.customize.control( 'background_color' );

Check if control exists.

hasControl = wp.customize.control.has( 'background_color' );

Deferred getting of `background_color` control until it exists, using callback.

wp.customize.control( 'background_color', function( control ) { ... } );

Get title and tagline controls when they both exist, using promise (only available when multiple IDs are present).

promise = wp.customize.control( 'blogname', 'blogdescription' );
promise.done( function( titleControl, taglineControl ) { ... } );

Get title and tagline controls when they both exist, using callback.

wp.customize.control( 'blogname', 'blogdescription', function( titleControl, taglineControl ) { ... } );

Getting setting value for `background_color` control.

value = wp.customize.control( 'background_color ').setting.get();
value = wp.customize( 'background_color' ).get(); // Same as above, since setting ID and control ID are the same.

Add new control for site title.

wp.customize.control.add( new wp.customize.Control( 'other_blogname', {
    setting: 'blogname',
    type: 'text',
    label: 'Site title',
    section: 'other_site_identify'
} ) );

Remove control.

wp.customize.control.remove( 'other_blogname' );

Listen for control being added.

wp.customize.control.bind( 'add', function( addedControl ) { ... } )

Listen for control being removed.

wp.customize.control.bind( 'removed', function( removedControl ) { ... } )

<static> defaultConstructor

Change objects contained within the main customize object to Settings.
Source:

<static> notifications :function

Collection of all global notifications.
Type:
  • function
Since:
  • 4.9.0
Source:
See:
Examples

Check if existing notification

exists = wp.customize.notifications.has( 'a_new_day_arrived' );

Obtain existing notification

notification = wp.customize.notifications( 'a_new_day_arrived' );

Obtain notification that may not exist yet.

wp.customize.notifications( 'a_new_day_arrived', function( notification ) { ... } );

Add a warning notification.

wp.customize.notifications.add( new wp.customize.Notification( 'midnight_almost_here', {
    type: 'warning',
    message: 'Midnight has almost arrived!',
    dismissible: true
} ) );

Remove a notification.

wp.customize.notifications.remove( 'a_new_day_arrived' );

<static> panel :function

Collection of all registered panels.
Type:
  • function
Since:
  • 4.0.0
Source:
See:
Examples

Loop over all registered panels.

wp.customize.panel.each( function( panel ) { ... } )

Getting nav_menus panel instance.

panel = wp.customize.panel( 'nav_menus' );

Expand dynamically-created panel when it exists.

wp.customize.panel( 'dynamically_created', function( panel ) {
    panel.expand();
} );

<static> previewer

Initialize Previewer
Source:

<static> reflowPaneContents

Sort panels, sections, controls by priorities. Hide empty sections and panels.
Since:
  • 4.1.0
Source:

<static> section :function

Collection of all registered sections.
Type:
  • function
Since:
  • 3.4.0
Source:
See:
Examples

Loop over all registered sections.

wp.customize.section.each( function( section ) { ... } )

Getting `title_tagline` section instance.

section = wp.customize.section( 'title_tagline' )

Expand dynamically-created section when it exists.

wp.customize.section( 'dynamically_created', function( section ) {
    section.expand();
} );

Methods

<private, static> _handleSettingValidities(args)

Handle setting_validities in an error response for the customize-save request. Add notifications to the settings and focus on the first control that has an invalid setting.
Parameters:
Name Type Description
args object
Properties
Name Type Argument Default Description
settingValidities object
focusInvalidControl boolean <optional>
 false
Since:
  • 4.6.0
Source:
Returns:
Type
void

<static> dirtyValues( [options])

Get the dirty setting values.
Parameters:
Name Type Argument Description
options object <optional>
 Options.
Properties
Name Type Argument Default Description
unsaved boolean <optional>
 false Whether only values not saved yet into a changeset will be returned (differential changes).
Since:
  • 4.7.0
Source:
Returns:
Dirty setting values.
Type
object

<static> findControlsForSettings(settingIds)

Find all controls associated with the given settings.
Parameters:
Name Type Description
settingIds Array:.<string:> Setting IDs.
Since:
  • 4.6.0
Source:
Returns:
Mapping setting ids to arrays of controls.
Type
object:.<string:, wp.customize.Control:>

<static> get()

Get all customize settings.
Source:
Returns:
Type
object

<static> requestChangesetUpdate( [changes] [, args])

Request updates to the changeset.
Parameters:
Name Type Argument Description
changes object <optional>
 Mapping of setting IDs to setting params each normally including a value property, or mapping to null. If not provided, then the changes will still be obtained from unsaved dirty settings.
args object <optional>
 Additional options for the save request.
Properties
Name Type Argument Default Description
autosave boolean <optional>
 false Whether changes will be stored in autosave revision if the changeset has been promoted from an auto-draft.
force boolean <optional>
 false Send request to update even when there are no changes to submit. This can be used to request the latest status of the changeset on the server.
title string <optional>
 Title to update in the changeset. Optional.
date string <optional>
 Date to update in the changeset. Optional.
Since:
  • 4.7.0
Source:
Returns:
Promise resolving with the response data.
Type
jQuery.Promise

<static> setDocumentTitle(documentTitle)

Set the document title of the customizer.
Parameters:
Name Type Description
documentTitle string
Since:
  • 4.1.0
Source:

<inner> focus( [params])

Expand a panel, section, or control and focus on the first focusable element.
Parameters:
Name Type Argument Description
params Object <optional>
Properties
Name Type Argument Description
completeCallback function <optional>
Since:
  • 4.1.0
Source:

Type Definitions

deferredControlsCallback(controls)

Callback for resolved controls.
Parameters:
Name Type Description
controls Array:.<wp.customize.Control:> Resolved controls.
Source:

deferredNotificationsCallback(notifications)

Callback for resolved notifications.
Parameters:
Name Type Description
notifications Array:.<wp.customize.Notification:> Resolved notifications.
Source:

deferredPanelsCallback(panels)

Callback for resolved panels.
Parameters:
Name Type Description
panels Array:.<wp.customize.Panel:> Resolved panels.
Source:

deferredSectionsCallback(sections)

Callback for resolved sections.
Parameters:
Name Type Description
sections Array:.<wp.customize.Section:> Resolved sections.
Source: