How to Use the WP Theme Customizer API for Dynamic Sites

There is a lazy way to use the Customizer, and then there is the grown-up way.

The lazy way is adding five color pickers, two text inputs, and calling it theme settings. The grown-up way is using the Customizer as a controlled interface for live external data: branch locations from an API, partner brands from a JSON feed, selectable layouts based on remote inventory, region lists, pricing tables, featured campaigns, whatever the site actually needs. That is where the wordpress theme customizer api gets interesting.

There is one caveat worth stating plainly: this is primarily a classic theme pattern, not the center of gravity for full block-theme work. The Customizer docs still position it as the canonical theme-options framework for themes and plugins, but modern block themes have shifted a lot of visual configuration into the Site Editor and theme.json. So this post is really about the places where the Customizer is still the right tool: classic themes, hybrid themes, and controlled option panels that benefit from live preview. :contentReference[oaicite:1]{index=1}

What wordpress theme customizer api actually means

The wordpress theme customizer api is WordPress’s framework for registering theme settings, exposing those settings as controls, and previewing changes live before publishing them. Its core object model is built around panels, sections, settings, and controls, all managed through WP_Customize_Manager. That matters because dynamic external-data controls still plug into the same object model; they are not a separate system. :contentReference[oaicite:2]{index=2}

The practical translation is simple: if you can turn an external data source into an array of valid choices, you can usually surface it in the Customizer cleanly.

The short framework

Step	What happens	Why it matters
1	Fetch dynamic data from an external source	Turns the control into something more useful than a static dropdown
2	Register a setting in the Customizer	Creates a safe storage target for the chosen value
3	Register a custom control	Lets you render the external data in a usable UI
4	Validate and sanitize the selected value	Prevents bad remote data from becoming a saved theme setting
5	Use the saved value in the theme output	Turns the selection into real frontend behavior

This is the important mental shift: the Customizer is not the data source. It is the selection layer.

Why custom controls matter for dynamic sites

Because a dynamic site usually needs more than a plain text box. If the theme setting is supposed to reference an external branch office, partner brand, property listing, or campaign object, you do not want editors typing that value manually and praying the slug matches. You want a controlled interface fed by real data.

The core WP_Customize_Control class is specifically meant to render input controls inside the Theme Customizer, and WordPress documents extension points like render_content() for PHP-rendered controls and print_template() / to_json() for JS-rendered controls. That is exactly what makes external-data controls possible without rebuilding the whole Customizer from scratch. :contentReference[oaicite:3]{index=3}

The right architecture for external dynamic data

External API / JSON feed
          │
          │ wp_remote_get() or cached fetch
          ▼
  Theme / plugin helper function
          │
          │ normalized array of choices
          ▼
 customize_register
          │
          ├─ add_setting()
          └─ add_control( custom control )
                    │
                    ▼
         Customizer UI renders choices
                    │
                    ▼
          Editor selects one item
                    │
                    ▼
      Theme mod / option is saved
                    │
                    ▼
   Frontend uses saved external reference

This is the clean architecture. External source on one side. Customizer as the decision UI. Theme setting as the saved result. No hardcoded dropdowns that go stale every three weeks.

Example 1: PHP custom control using a remote JSON feed

This example registers a Customizer section, creates a setting for a selected external location, fetches a remote JSON feed, and renders a dropdown control populated with live options. The control stores only the selected location ID, not the whole remote object. That is the right move. Keep the saved value small and stable.

/**
 * Fetch and normalize external location data.
 */
function mytheme_get_remote_locations() {
	$transient_key = 'mytheme_remote_locations';
	$cached        = get_transient( $transient_key );

	if ( false !== $cached ) {
		return $cached;
	}

	$response = wp_remote_get(
		'https://api.example.com/locations',
		array(
			'timeout' => 8,
		)
	);

	if ( is_wp_error( $response ) ) {
		return array();
	}

	$body = wp_remote_retrieve_body( $response );
	$data = json_decode( $body, true );

	if ( ! is_array( $data ) ) {
		return array();
	}

	$choices = array();

	foreach ( $data as $item ) {
		if ( empty( $item['id'] ) || empty( $item['name'] ) ) {
			continue;
		}

		$choices[ sanitize_text_field( $item['id'] ) ] = sanitize_text_field( $item['name'] );
	}

	set_transient( $transient_key, $choices, HOUR_IN_SECONDS );

	return $choices;
}

/**
 * Custom select control for external locations.
 */
class MyTheme_Location_Select_Control extends WP_Customize_Control {
	public $type = 'mytheme_location_select';
	public $choices = array();

	public function render_content() {
		if ( empty( $this->choices ) ) {
			echo '<p>No locations available right now.</p>';
			return;
		}
		?>
		<label>
			<?php if ( ! empty( $this->label ) ) : ?>
				<span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span>
			<?php endif; ?>

			<?php if ( ! empty( $this->description ) ) : ?>
				<span class="description customize-control-description"><?php echo esc_html( $this->description ); ?></span>
			<?php endif; ?>

			<select <?php $this->link(); ?>>
				<option value="">Select a location</option>
				<?php foreach ( $this->choices as $value => $label ) : ?>
					<option value="<?php echo esc_attr( $value ); ?>" <?php selected( $this->value(), $value ); ?>>
						<?php echo esc_html( $label ); ?>
					</option>
				<?php endforeach; ?>
			</select>
		</label>
		<?php
	}
}

/**
 * Register the setting and control.
 */
add_action( 'customize_register', 'mytheme_register_dynamic_location_control' );

function mytheme_register_dynamic_location_control( $wp_customize ) {

	$wp_customize->add_section(
		'mytheme_dynamic_data',
		array(
			'title'    => __( 'Dynamic Data', 'mytheme' ),
			'priority' => 40,
		)
	);

	$wp_customize->add_setting(
		'mytheme_selected_location',
		array(
			'default'           => '',
			'sanitize_callback' => 'sanitize_text_field',
			'transport'         => 'refresh',
		)
	);

	$wp_customize->add_control(
		new MyTheme_Location_Select_Control(
			$wp_customize,
			'mytheme_selected_location_control',
			array(
				'label'       => __( 'Featured Location', 'mytheme' ),
				'description' => __( 'Pick a location from the external locations feed.', 'mytheme' ),
				'section'     => 'mytheme_dynamic_data',
				'settings'    => 'mytheme_selected_location',
				'choices'     => mytheme_get_remote_locations(),
			)
		)
	);
}

This is the safest basic pattern because the external fetch is cached, the choices are normalized, and the saved setting is just the chosen key. That is how you keep the Customizer fast enough to stay civilized.

Why caching remote data matters

Because the Customizer is not the place to behave like a streaming dashboard.

If every panel load hits an external API directly, your theme settings UI becomes fragile, slow, and weirdly dependent on someone else’s uptime. That is bad architecture. Cache the feed, normalize it, and let the control render from a stable local array. If the external source is briefly down, your Customizer should still behave like a respectable admin interface, not a nervous breakdown.

Example 2: JavaScript-rendered custom control for richer dynamic data

Sometimes a plain select field is not enough. Maybe the external source includes labels, thumbnails, statuses, pricing tiers, or region metadata. That is where a JS-rendered control becomes more interesting.

WordPress documents JS/Underscore-rendered controls and explains that additional control data can be pushed to JavaScript by overriding to_json(). That is the move you want when a control needs more than a flat label/value list. :contentReference[oaicite:4]{index=4}

class MyTheme_Remote_Brand_Control extends WP_Customize_Control {
	public $type = 'mytheme_remote_brand';
	public $brands = array();

	public function enqueue() {
		wp_enqueue_script(
			'mytheme-customizer-controls',
			get_template_directory_uri() . '/assets/js/customizer-controls.js',
			array( 'customize-controls', 'jquery' ),
			'1.0',
			true
		);
	}

	public function to_json() {
		parent::to_json();
		$this->json['brands'] = $this->brands;
	}

	public function content_template() {
		?>
		<label>
			<# if ( data.label ) { #>
				<span class="customize-control-title">{{ data.label }}</span>
			<# } #>

			<# if ( data.description ) { #>
				<span class="description customize-control-description">{{ data.description }}</span>
			<# } #>

			<select {{{ data.link }}}>
				<option value="">Select a brand</option>
				<# _.each( data.brands, function( brand ) { #>
					<option value="{{ brand.id }}" <# if ( data.value === brand.id ) { #>selected<# } #>>
						{{ brand.name }} — {{ brand.region }}
					</option>
				<# } ); #>
			</select>
		</label>
		<?php
	}
}

function mytheme_get_remote_brands() {
	$response = wp_remote_get( 'https://api.example.com/brands', array( 'timeout' => 8 ) );

	if ( is_wp_error( $response ) ) {
		return array();
	}

	$data = json_decode( wp_remote_retrieve_body( $response ), true );

	if ( ! is_array( $data ) ) {
		return array();
	}

	$brands = array();

	foreach ( $data as $item ) {
		if ( empty( $item['id'] ) || empty( $item['name'] ) ) {
			continue;
		}

		$brands[] = array(
			'id'     => sanitize_text_field( $item['id'] ),
			'name'   => sanitize_text_field( $item['name'] ),
			'region' => ! empty( $item['region'] ) ? sanitize_text_field( $item['region'] ) : '',
		);
	}

	return $brands;
}

add_action( 'customize_register', 'mytheme_register_remote_brand_control' );

function mytheme_register_remote_brand_control( $wp_customize ) {
	$wp_customize->add_setting(
		'mytheme_featured_brand',
		array(
			'default'           => '',
			'sanitize_callback' => 'sanitize_text_field',
		)
	);

	$wp_customize->add_control(
		new MyTheme_Remote_Brand_Control(
			$wp_customize,
			'mytheme_featured_brand_control',
			array(
				'label'       => __( 'Featured Brand', 'mytheme' ),
				'description' => __( 'Choose a brand from the external catalog.', 'mytheme' ),
				'section'     => 'mytheme_dynamic_data',
				'settings'    => 'mytheme_featured_brand',
				'brands'      => mytheme_get_remote_brands(),
			)
		)
	);
}

This version is more flexible because the control can render richer metadata without turning the PHP side into a miserable string-builder.

How the saved value should be used in the theme

Here is where people get sloppy. The Customizer control is not supposed to save the whole remote payload. It should save the smallest stable reference, usually an ID or slug. Then the frontend can use that saved value to retrieve the right local cached data, or resolve it against a lightweight fetch layer when rendering.

That is the important separation of concerns:

Layer	What it should store	Why
Customizer setting	External ID or slug	Keeps the saved option stable and light
Theme helper function	Resolved display object	Turns the saved ID into usable frontend data
External API cache	Normalized payload array	Prevents repeated slow remote requests

If you save the whole remote object in a theme mod because it felt convenient, you are asking for stale data and awkward cleanup later.

When this API is still the right tool

The Customizer is still a good fit when the user needs live preview, when the theme is classic or hybrid, and when the setting is clearly “theme behavior” rather than general site content. Featured branch selector. hero campaign source. region selector. remote brand choice. layout source. Those are reasonable Customizer jobs.

It is a bad fit when you are really building content management inside a theme setting. If the value behaves more like content than presentation logic, it probably belongs in a post type, an options page, or a dedicated admin UI instead of the Customizer.

What docs do not tell you

The hard part is rarely the control itself. The hard part is deciding what should be fetched remotely, what should be cached locally, and what should actually be saved as the final setting.

External dynamic controls can rot quietly. If the remote API changes field names or starts returning weird payloads, your Customizer can degrade in ugly but subtle ways. Normalize everything before it touches the control.

The Customizer is not the future of every theme workflow. For block themes, the Site Editor has taken over a lot of terrain. The Customizer still matters, but mostly where classic-theme settings and live preview remain the better fit. :contentReference[oaicite:5]{index=5}

JS-rendered controls are often cleaner for richer data. Once the external source includes multiple display fields, thumbnails, regions, or statuses, fighting everything through plain PHP markup becomes less noble and more masochistic.

Our experience with wordpress theme customizer api work

Our experience with the wordpress theme customizer api is that it gets underestimated because too many people remember it as a place for logos, colors, and some random homepage text field from 2017. That is a very limited view of what it can do in classic-theme environments.

Used properly, it is a controlled live-preview interface for theme-level decisions, and that makes it surprisingly good for dynamic-site settings that depend on external data. The mistake is not using external data. The mistake is letting the external data become the UI directly without normalization, caching, or sane saved values. That is where “dynamic” turns into “fragile.”

And honestly, that is probably the question worth leaving on the table: if your dynamic site still relies on hardcoded theme settings that go stale the moment an external catalog changes, are you really building a flexible theme, or just a static options panel wearing a modern buzzword?