WordPress wp_script_add_data Example: Add defer and async Safely

Last reviewed: May 1, 2026

Front-end performance work often stalls because scripts are enqueued correctly but still loaded with the wrong execution strategy. wp_script_add_data() is the native helper for attaching metadata to an already registered script, including modern loading strategies such as defer and async.

This guide shows how to use wp_script_add_data() safely so WordPress controls script behavior without brittle manual tag rewriting.

Register or enqueue the handle first

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

function vulnwp_enqueue_filters_script() {
	wp_enqueue_script(
		'vulnwp-filters',
		get_stylesheet_directory_uri() . '/assets/js/filters.js',
		array(),
		null,
		true
	);

	wp_script_add_data( 'vulnwp-filters', 'strategy', 'defer' );
}

The WordPress reference is explicit here: the helper works only if the script handle already exists.

Use strategy metadata for loading behavior, not for config

wp_script_add_data() is for metadata about the script tag. If the code needs runtime configuration, use wp_add_inline_script() instead of forcing config into the wrong helper.

Defer and async are not interchangeable

defer preserves execution order relative to other deferred scripts. async does not. Choose based on the dependency graph, not on whichever sounds faster.

Keep the handle stable across theme and plugin layers

If another part of the stack already registers the script, add metadata to the same handle instead of duplicating the asset with a slightly different name.

Production checklist

• Attach metadata only after the script is registered or enqueued.
• Use strategy for loading behavior, not config objects.
• Pick defer or async based on real dependency order.
• Retest any script that depends on DOM readiness or localized globals.
• Keep script handles consistent across theme and plugin code.
• Verify the rendered script tag in production HTML, not only in PHP.

Common mistakes

• Calling the helper before the handle exists. The metadata never attaches.
• Using async on ordered dependency chains. Execution can break quietly.
• Trying to pass config through script metadata. That belongs in inline data helpers.
• Duplicating the same script under multiple handles. Asset control becomes inconsistent.
• Assuming performance wins without front-end verification. Script timing changes can create regressions.

Related reading

If the asset itself still needs proper registration and dependencies, pair this with the wp_enqueue_script guide. If the script also needs runtime data from PHP, continue with the wp_localize_script article.

References and further reading

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