{"id":5576,"date":"2026-02-12T20:44:50","date_gmt":"2026-02-13T01:44:50","guid":{"rendered":"https:\/\/chubes.net\/?documentation=wordpress-customizer-api-overview"},"modified":"2026-03-13T03:28:13","modified_gmt":"2026-03-13T07:28:13","slug":"wordpress-customizer-api-overview","status":"publish","type":"documentation","link":"https:\/\/chubes.net\/docs\/wordpress-core\/customizer\/wordpress-customizer-api-overview\/","title":{"rendered":"WordPress Customizer API Overview"},"content":{"rendered":"<p>The WordPress Customizer (Theme Customization API) provides a framework for live-previewing any changes to WordPress settings. Introduced in WordPress 3.4, it allows developers to customize and preview changes to the site before publishing them.<\/p><h2 class=\"wp-block-heading\">Architecture<\/h2><p>The Customizer consists of four primary object types that work together in a hierarchical structure:<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\"><\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code\"><code>Panels (optional containers)\n  \u2514\u2500\u2500 Sections (containers for controls)\n       \u2514\u2500\u2500 Controls (UI elements)\n            \u2514\u2500\u2500 Settings (data storage)<\/code><\/pre><\/div><h3 class=\"wp-block-heading\">Core Classes<\/h3><figure class=\"wp-block-table\"><table><thead><tr><th>Class<\/th><th>Purpose<\/th><th>Since<\/th><\/tr><\/thead><tbody><tr><td><code>WP_Customize_Manager<\/code><\/td><td>Central orchestrator, factory for all components<\/td><td>3.4<\/td><\/tr><tr><td><code>WP_Customize_Setting<\/code><\/td><td>Handles data storage, sanitization, and preview<\/td><td>3.4<\/td><\/tr><tr><td><code>WP_Customize_Section<\/code><\/td><td>UI container for controls<\/td><td>3.4<\/td><\/tr><tr><td><code>WP_Customize_Panel<\/code><\/td><td>UI container for sections<\/td><td>4.0<\/td><\/tr><tr><td><code>WP_Customize_Control<\/code><\/td><td>UI element for user input<\/td><td>3.4<\/td><\/tr><tr><td><code>WP_Customize_Selective_Refresh<\/code><\/td><td>Partial content refresh<\/td><td>4.5<\/td><\/tr><tr><td><code>WP_Customize_Partial<\/code><\/td><td>Defines refreshable content regions<\/td><td>4.5<\/td><\/tr><\/tbody><\/table><\/figure><h2 class=\"wp-block-heading\">Live Preview System<\/h2><p>The Customizer implements a sophisticated live preview system:<\/p><h3 class=\"wp-block-heading\">Preview Transport Methods<\/h3><ol class=\"wp-block-list\"><li><strong><code>refresh<\/code><\/strong> (default) &#8211; Reloads the entire preview iframe when setting changes<\/li><li><strong><code>postMessage<\/code><\/strong> &#8211; Uses JavaScript to update preview without reload<\/li><\/ol><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">php<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-php\"><code class=\"language-php\">$wp_customize-&gt;add_setting( &#039;my_setting&#039;, array(\n    &#039;transport&#039; =&gt; &#039;postMessage&#039;, \/\/ Enable JS-based preview\n) );<\/code><\/pre><\/div><h3 class=\"wp-block-heading\">Preview Flow<\/h3><ol class=\"wp-block-list\"><li>User makes changes in the Customizer pane<\/li><li>Changes are stored in a <strong>changeset<\/strong> (post type: <code>customize_changeset<\/code>)<\/li><li>Preview iframe displays changes without saving to database<\/li><li>On publish, settings are persisted to their storage locations<\/li><\/ol><h2 class=\"wp-block-heading\">Changesets (Since 4.7)<\/h2><p>Changesets allow saving customizations without publishing:<\/p><ul class=\"wp-block-list\"><li><strong>UUID-based<\/strong> &#8211; Each changeset has a unique identifier<\/li><li><strong>Transactional<\/strong> &#8211; All-or-nothing publishing<\/li><li><strong>Schedulable<\/strong> &#8211; Can be scheduled for future publishing<\/li><li><strong>Collaborative<\/strong> &#8211; Supports autosave revisions per user<\/li><li><strong>Branching<\/strong> &#8211; Optional concurrent changeset support<\/li><\/ul><h3 class=\"wp-block-heading\">Changeset Statuses<\/h3><figure class=\"wp-block-table\"><table><thead><tr><th>Status<\/th><th>Description<\/th><\/tr><\/thead><tbody><tr><td><code>auto-draft<\/code><\/td><td>Unsaved work in progress<\/td><\/tr><tr><td><code>draft<\/code><\/td><td>Saved but not published<\/td><\/tr><tr><td><code>pending<\/code><\/td><td>Awaiting review<\/td><\/tr><tr><td><code>future<\/code><\/td><td>Scheduled for publication<\/td><\/tr><tr><td><code>publish<\/code><\/td><td>Applied to the site<\/td><\/tr><\/tbody><\/table><\/figure><h2 class=\"wp-block-heading\">Selective Refresh (Since 4.5)<\/h2><p>Selective refresh updates only specific portions of the preview:<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">php<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-php\"><code class=\"language-php\">$wp_customize-&gt;selective_refresh-&gt;add_partial( &#039;blogname&#039;, array(\n    &#039;selector&#039; =&gt; &#039;.site-title a&#039;,\n    &#039;render_callback&#039; =&gt; function() {\n        bloginfo( &#039;name&#039; );\n    },\n) );<\/code><\/pre><\/div><h3 class=\"wp-block-heading\">Benefits<\/h3><ul class=\"wp-block-list\"><li><strong>Performance<\/strong> &#8211; Updates only what changed<\/li><li><strong>UX<\/strong> &#8211; Smoother preview experience<\/li><li><strong>Reliability<\/strong> &#8211; Maintains scroll position and state<\/li><\/ul><h2 class=\"wp-block-heading\">Registration Hook<\/h2><p>All Customizer components should be registered on the <code>customize_register<\/code> action:<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">php<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-php\"><code class=\"language-php\">add_action( &#039;customize_register&#039;, function( $wp_customize ) {\n    \/\/ Add panels, sections, controls, settings, and partials\n} );<\/code><\/pre><\/div><h2 class=\"wp-block-heading\">Basic Example<\/h2><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">php<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-php\"><code class=\"language-php\">add_action( &#039;customize_register&#039;, function( $wp_customize ) {\n    \/\/ Add a section\n    $wp_customize-&gt;add_section( &#039;my_section&#039;, array(\n        &#039;title&#039;    =&gt; __( &#039;My Section&#039; ),\n        &#039;priority&#039; =&gt; 30,\n    ) );\n\n    \/\/ Add a setting\n    $wp_customize-&gt;add_setting( &#039;my_color&#039;, array(\n        &#039;default&#039;           =&gt; &#039;#000000&#039;,\n        &#039;sanitize_callback&#039; =&gt; &#039;sanitize_hex_color&#039;,\n        &#039;transport&#039;         =&gt; &#039;postMessage&#039;,\n    ) );\n\n    \/\/ Add a control\n    $wp_customize-&gt;add_control( new WP_Customize_Color_Control(\n        $wp_customize,\n        &#039;my_color&#039;,\n        array(\n            &#039;label&#039;   =&gt; __( &#039;My Color&#039; ),\n            &#039;section&#039; =&gt; &#039;my_section&#039;,\n        )\n    ) );\n} );<\/code><\/pre><\/div><h2 class=\"wp-block-heading\">Built-in Control Types<\/h2><h3 class=\"wp-block-heading\">Basic Controls (via <code>type<\/code> argument)<\/h3><ul class=\"wp-block-list\"><li><code>text<\/code> &#8211; Text input (default)<\/li><li><code>checkbox<\/code> &#8211; Checkbox<\/li><li><code>textarea<\/code> &#8211; Multi-line text<\/li><li><code>radio<\/code> &#8211; Radio buttons (requires <code>choices<\/code>)<\/li><li><code>select<\/code> &#8211; Dropdown (requires <code>choices<\/code>)<\/li><li><code>dropdown-pages<\/code> &#8211; Page selector<\/li><li><code>email<\/code>, <code>url<\/code>, <code>number<\/code>, <code>hidden<\/code>, <code>date<\/code> &#8211; HTML5 inputs<\/li><\/ul><h3 class=\"wp-block-heading\">Specialized Control Classes<\/h3><ul class=\"wp-block-list\"><li><code>WP_Customize_Color_Control<\/code> &#8211; Color picker<\/li><li><code>WP_Customize_Media_Control<\/code> &#8211; Media library attachment<\/li><li><code>WP_Customize_Image_Control<\/code> &#8211; Image upload<\/li><li><code>WP_Customize_Upload_Control<\/code> &#8211; File upload<\/li><li><code>WP_Customize_Cropped_Image_Control<\/code> &#8211; Image with cropping<\/li><li><code>WP_Customize_Code_Editor_Control<\/code> &#8211; Syntax-highlighted code editor<\/li><li><code>WP_Customize_Date_Time_Control<\/code> &#8211; Date\/time picker<\/li><\/ul><h2 class=\"wp-block-heading\">Capability Model<\/h2><p>The Customizer uses WordPress capabilities for access control:<\/p><ul class=\"wp-block-list\"><li><strong><code>customize<\/code><\/strong> &#8211; Meta capability that maps to <code>edit_theme_options<\/code><\/li><li>Controls inherit capability from their associated settings<\/li><li>Sections and panels have their own <code>capability<\/code> property<\/li><\/ul><h2 class=\"wp-block-heading\">Theme Support<\/h2><p>Settings can require theme support:<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">php<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-php\"><code class=\"language-php\">$wp_customize-&gt;add_setting( &#039;header_image&#039;, array(\n    &#039;theme_supports&#039; =&gt; &#039;custom-header&#039;,\n) );<\/code><\/pre><\/div><h2 class=\"wp-block-heading\">Starter Content (Since 4.7)<\/h2><p>Themes can provide starter content that&#8217;s imported on fresh installations:<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">php<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-php\"><code class=\"language-php\">add_theme_support( &#039;starter-content&#039;, array(\n    &#039;widgets&#039; =&gt; array( \/* ... *\/ ),\n    &#039;posts&#039; =&gt; array( \/* ... *\/ ),\n    &#039;nav_menus&#039; =&gt; array( \/* ... *\/ ),\n    &#039;options&#039; =&gt; array( \/* ... *\/ ),\n    &#039;theme_mods&#039; =&gt; array( \/* ... *\/ ),\n) );<\/code><\/pre><\/div><h2 class=\"wp-block-heading\">JavaScript API<\/h2><p>The Customizer has a robust JavaScript API (<code>wp.customize<\/code>):<\/p><div class=\"code-block-wrapper\"><div class=\"code-block-header\"><span class=\"code-block-language\">javascript<\/span><button class=\"code-copy-btn\" aria-label=\"Copy code\"><svg><use href=\"https:\/\/chubes.net\/wp-content\/themes\/chubes\/assets\/icons\/chubes.svg#icon-copy\"><\/use><\/svg><\/button><\/div><pre data-chubes-enhanced class=\"wp-block-code language-javascript\"><code class=\"language-javascript\">\/\/ React to setting changes\nwp.customize( &#039;my_setting&#039;, function( setting ) {\n    setting.bind( function( value ) {\n        \/\/ Update preview\n    } );\n} );\n\n\/\/ From preview frame\nwp.customize.preview.bind( &#039;active&#039;, function() {\n    \/\/ Preview is ready\n} );<\/code><\/pre><\/div><h2 class=\"wp-block-heading\">Related Files<\/h2><figure class=\"wp-block-table\"><table><thead><tr><th>File<\/th><th>Purpose<\/th><\/tr><\/thead><tbody><tr><td><code>class-wp-customize-manager.php<\/code><\/td><td>Manager class<\/td><\/tr><tr><td><code>class-wp-customize-setting.php<\/code><\/td><td>Settings class<\/td><\/tr><tr><td><code>class-wp-customize-section.php<\/code><\/td><td>Sections class<\/td><\/tr><tr><td><code>class-wp-customize-panel.php<\/code><\/td><td>Panels class<\/td><\/tr><tr><td><code>class-wp-customize-control.php<\/code><\/td><td>Controls class<\/td><\/tr><tr><td><code>customize\/<\/code><\/td><td>Specialized subclasses<\/td><\/tr><\/tbody><\/table><\/figure>","protected":false},"excerpt":{"rendered":"<p>The WordPress Customizer (Theme Customization API) provides a framework for live-previewing any changes to WordPress settings. Introduced in WordPress 3.4, it allows developers to customize and preview changes to the&#8230;<\/p>\n","protected":false},"featured_media":0,"template":"","meta":{"footnotes":""},"tags":[],"project":[610],"project_type":[749],"class_list":["post-5576","documentation","type-documentation","status-publish","hentry","project-customizer","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\/5576","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":3,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/documentation\/5576\/revisions"}],"predecessor-version":[{"id":8947,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/documentation\/5576\/revisions\/8947"}],"wp:attachment":[{"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/media?parent=5576"}],"wp:term":[{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/tags?post=5576"},{"taxonomy":"project","embeddable":true,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/project?post=5576"},{"taxonomy":"project_type","embeddable":true,"href":"https:\/\/chubes.net\/wp-json\/wp\/v2\/project_type?post=5576"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}