WordPress wp_localize_script Example: Pass Script Data the Right Way

Last reviewed: April 24, 2026

wp_localize_script() is one of the most overused WordPress helpers because it was historically used for almost every PHP-to-JavaScript bridge. WordPress now documents a more precise rule: use localization for translatable strings, and use wp_add_inline_script() when you need to inject generic configuration data.

This guide shows both patterns so your front-end code gets the right data without leaning on outdated cargo-cult examples.

Register and enqueue the script first

<?php
add_action( 'wp_enqueue_scripts', 'vulnwp_enqueue_frontend_script' );

function vulnwp_enqueue_frontend_script() {
	wp_enqueue_script(
		'vulnwp-frontend',
		get_theme_file_uri( 'assets/js/frontend.js' ),
		array(),
		wp_get_theme()->get( 'Version' ),
		true
	);
}

Both wp_localize_script() and wp_add_inline_script() need a registered or enqueued handle to attach to. If the handle does not exist, the data bridge fails silently.

Use wp_localize_script for translatable strings

wp_localize_script(
	'vulnwp-frontend',
	'vulnwpI18n',
	array(
		'expandLabel'  => __( 'Expand section', 'vulnwp' ),
		'collapseLabel' => __( 'Collapse section', 'vulnwp' ),
		'copySuccess'  => __( 'Copied to clipboard.', 'vulnwp' ),
	)
);

This is true localization: the values are strings meant for translation and user-facing messaging.

Use wp_add_inline_script for generic config

$config = array(
	'apiBase'   => esc_url_raw( rest_url( 'vulnwp/v1/' ) ),
	'nonce'     => wp_create_nonce( 'wp_rest' ),
	'cacheTtl'  => 300,
	'isLoggedIn' => is_user_logged_in(),
);

wp_add_inline_script(
	'vulnwp-frontend',
	'window.vulnwpConfig = ' . wp_json_encode( $config ) . ';',
	'before'
);

The inline script runs before the main bundle, so your front-end code can read window.vulnwpConfig immediately.

Read the values in JavaScript

const { apiBase, nonce } = window.vulnwpConfig;

fetch(`${apiBase}status`, {
	headers: {
		'X-WP-Nonce': nonce,
	},
})
	.then((response) => response.json())
	.then((data) => {
		console.log(data);
	});

Keep the client-side contract small. Do not dump entire PHP option arrays into JavaScript just because it is convenient.

Production checklist

• Enqueue the target script handle before attaching data.
• Use wp_localize_script() for real translatable strings.
• Use wp_add_inline_script() for config objects and runtime data.
• Encode data with wp_json_encode().
• Keep exposed data minimal and public-safe.
• Prefix the JavaScript object name to avoid collisions.

Common mistakes

• Using localization for everything. That blurs translation and runtime config concerns.
• Attaching data before the script handle exists. No handle, no output.
• Exposing secrets or internal tokens. Anything rendered in HTML is public to the browser.
• Creating generic object names like config. Global collisions are common on WordPress sites.
• Passing massive nested arrays. That inflates page weight and client complexity.

Related reading

If the front end calls a custom endpoint, pair this with the register_rest_route example. For script loading discipline, combine it with the wp_enqueue_script guide.

References and further reading

• WordPress Code Reference: wp_localize_script()
• WordPress Code Reference: wp_add_inline_script()
• WordPress Code Reference: wp_enqueue_script()