The WordPress Customizer provides a live-preview interface for customizing theme settings. Unlike the old Theme Options pages that required page refreshes to see changes, the Customizer lets users see their changes in real time. For theme and plugin developers, the Customizer API provides a standardized way to add configuration options.
This guide covers how to add custom options to the WordPress Customizer, from basic settings to advanced controls with live preview.
Customizer Structure
The Customizer has three levels: panels (major sections), sections (groups of settings within a panel), and controls (individual settings). Panels organize sections, sections organize controls, and controls let users modify settings. Every setting must have a registered control to appear in the Customizer.
Add all Customizer code during the customize_register action hook. The hook provides a $wp_customize object that’s the main API for adding panels, sections, settings, and controls.
Adding Sections and Panels
Use $wp_customize->add_panel() to create a major grouping, and $wp_customize->add_section() to create sub-groups within panels. Each accepts an ID and an array of arguments including title, description, priority, and capability. Sections can be added without a parent panel for simpler structures.
Use descriptive, user-friendly titles and descriptions. The description appears as tooltip text under the section title in the Customizer interface. Prioritize your sections so the most important ones appear first.
Adding Settings and Controls
Use $wp_customize->add_setting() to register a theme modification. Parameters include default value, transport type (‘refresh’ or ‘postMessage’), sanitize_callback, and capability. Use $wp_customize->add_control() to create the UI element for the setting. WordPress provides built-in control types: text, textarea, checkbox, select, radio, color, image, and cropped_image.
Use the ‘transport’ parameter to control how changes are applied. ‘refresh’ reloads the entire preview. ‘postMessage’ updates the preview via JavaScript, which is faster and smoother but requires custom JavaScript to apply the changes.
Live Preview with JavaScript
For a smooth live preview experience, enqueue a customizer preview JavaScript file on the customize_preview_init hook. Use the wp.customize API in this file to listen for setting changes and apply them to the preview in real time. Bind to setting changes with wp.customize(setting_id, function(value) { value.bind(function(to) { … }); }).
Update CSS properties via jQuery or direct DOM manipulation for instant feedback. For color settings, set css(). For text settings, update text(). For visibility toggles, use show()/hide().
Custom Control Types
When the built-in control types aren’t sufficient, create custom control types by extending WP_Customize_Control. Override the render_content() method to output custom HTML for your control. WordPress provides several base control classes: WP_Customize_Color_Control, WP_Customize_Image_Control, WP_Customize_Upload_Control, and WP_Customize_Cropped_Image_Control.
Register your custom control class with $wp_customize->register_control_type(). This tells the Customizer JavaScript how to handle your custom control during the live preview.
The Bottom Line
The Customizer API is the recommended way to add theme options in WordPress. Use the customize_register hook to add panels, sections, settings, and controls. Use postMessage for a smooth live preview experience. Create custom control types for specialized inputs. The Customizer provides a consistent, user-friendly interface that’s familiar to all WordPress users.