The supported way to add a JavaScript file to a WordPress site is to enqueue it with wp_enqueue_script() from the wp_enqueue_scripts action. For a small snippet tied to that file, use wp_add_inline_script(). Choose the enqueue hook for the part of WordPress where the code should run, and make sure the active theme calls wp_head() and wp_footer() so WordPress can print queued scripts.
Choose the right way to add the script
For code you expect to maintain, reuse, or debug, put JavaScript in its own file and enqueue that file. WordPress documents wp_enqueue_script() as the recommended way to link scripts to generated pages. Enqueuing lets WordPress manage script registration, dependencies, and output rather than relying on a manually inserted <script> tag.
Use inline JavaScript only when a short snippet belongs with an enqueued file—for example, a small initialization call. Add it with wp_add_inline_script() and attach it to the enqueued file’s handle. If a third-party provider requires a literal script block or a particular placement, follow its documented integration method, but do not assume that pasting arbitrary code into a theme file is safe or reliable.
| Need | Use |
|---|---|
| A reusable or maintained JavaScript file | wp_enqueue_script() |
| A short snippet associated with that file | wp_add_inline_script() |
| Code for WordPress admin screens | admin_enqueue_scripts |
| Code for the login screen | login_enqueue_scripts |
| JavaScript written as an ES module | wp_enqueue_script_module() |
The examples below are patterns to adapt, not code tested against a particular site. Use a unique handle, a real file path, a suitable version, and the dependencies your script actually needs.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
Enqueue an external JavaScript file on the front end
Place the JavaScript file in your theme or plugin, then register an enqueue callback on wp_enqueue_scripts. For a theme asset, get_theme_file_uri() builds its URL. The Theme Handbook’s guidance on including assets covers the theme-asset approach.
<?php
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_custom_script' );
function mytheme_enqueue_custom_script() {
wp_enqueue_script(
'mytheme-custom',
get_theme_file_uri( 'assets/js/custom.js' ),
array(),
'1.0.0',
array( 'in_footer' => true )
);
}Save that PHP in a theme’s functions.php or in a plugin that belongs to the site, and put the JavaScript at assets/js/custom.js relative to the theme. A site-specific plugin is often a better home for functionality that should remain active if the theme changes; theme-specific behavior can live with the theme. Avoid editing a parent theme that may be updated over your changes.
What each argument does
mytheme-customis the handle: WordPress uses it to identify the script. Choose a distinctive name to reduce collisions with themes and plugins.- The second argument is the script URL. Change the path to match the file’s actual location. A misspelled or misplaced file commonly results in a 404.
- The dependencies array is empty in this example. If the script relies on another registered script, list that dependency’s handle so WordPress can order the output.
1.0.0is a version string used in the script URL. Update it when you need a new URL after changing the asset; use a versioning approach appropriate to your release process.in_footerrequests footer placement. It does not guarantee output if the active theme fails to callwp_footer().
See the WordPress wp_enqueue_script() reference for the current parameters and behavior.
Attach a short inline snippet to the enqueued file
When an inline fragment belongs with a script you already enqueue, use wp_add_inline_script() with the same handle. The third argument controls placement: use before to add the snippet before the file, or after to add it after. The default placement is after.
<?php
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_custom_script' );
function mytheme_enqueue_custom_script() {
wp_enqueue_script(
'mytheme-custom',
get_theme_file_uri( 'assets/js/custom.js' ),
array(),
'1.0.0',
array( 'in_footer' => true )
);
$inline_code = 'window.myThemeFeature = true;';
wp_add_inline_script( 'mytheme-custom', $inline_code, 'before' );
}This example uses a fixed, trusted string. Do not concatenate raw user input, database content, or third-party data into executable JavaScript. If a value must be represented in inline JavaScript, validate and sanitize it for its intended use, then escape it for the output context. WordPress documents esc_js() for values in inline JavaScript; escaping is not a substitute for deciding whether the value should be executable in the first place.
For larger inline behavior, move the code into a file. Keep data and program code separate wherever practical, and enqueue the file that owns the behavior.
Select the correct WordPress area
The action determines where your callback runs. Use wp_enqueue_scripts for front-end pages, admin_enqueue_scripts for admin screens, and login_enqueue_scripts for the login screen. Do not load a front-end-only script globally in the dashboard unless it is needed there.
For admin assets, the action passes a screen identifier that can be used to limit loading. For example, the general shape is:
Recommended Free Tools
Rank #3
<?php
add_action( 'admin_enqueue_scripts', 'myplugin_enqueue_admin_script' );
function myplugin_enqueue_admin_script( $hook_suffix ) {
if ( 'toplevel_page_myplugin' !== $hook_suffix ) {
return;
}
wp_enqueue_script(
'myplugin-admin',
plugin_dir_url( __FILE__ ) . 'assets/js/admin.js',
array(),
'1.0.0',
array( 'in_footer' => true )
);
}Replace the screen identifier and file URL with values for your plugin. For a login-screen script, attach the callback to login_enqueue_scripts and enqueue only code that the login page needs. Keep the scope narrow: unnecessary site-wide scripts add work to pages that do not use them.
Choose head, footer, defer, or async deliberately
Placement and loading strategy affect when code runs. A footer script is usually suitable when the page can render before the script executes, but a script that must act early or provide a dependency for other code may need different handling. Confirm the behavior your script requires rather than moving every asset to one location by default.
WordPress 6.3 added the $args parameter to wp_enqueue_script(), including strategy options for defer or async. Deferred scripts run after the document tree is loaded and before DOMContentLoaded. Async scripts can execute as soon as they are available, so execution order is not suitable for code that depends on another script being evaluated first. Review the current function reference before relying on version-specific parameters.
For versions and arguments that support it, a deferred footer script can be requested like this:
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Rank #4
<?php
wp_enqueue_script(
'mytheme-custom',
get_theme_file_uri( 'assets/js/custom.js' ),
array(),
'1.0.0',
array(
'in_footer' => true,
'strategy' => 'defer',
)
);Use async only when the script is independent of other scripts and its execution timing is acceptable. If it depends on jQuery, another library, or inline setup code, preserve the required order and verify the resulting page behavior.
Why wp_head() and wp_footer() matter
Enqueueing records a script for WordPress to print; the active theme’s template functions provide the output locations. wp_head() prints output associated with the head, while wp_footer() prints output before the closing body tag. If a theme does not call the relevant function, queued assets or hook output for that location may not appear. Check the theme templates before changing your enqueue code to compensate.
Use the module API for JavaScript modules
For code authored as an ES module, use WordPress’s wp_enqueue_script_module() API rather than treating module code as an ordinary classic script. Module dependencies and import-map handling differ from classic script enqueues.
WordPress documents a timing condition for modules that use dynamic imports: they need footer placement or deferred loading so the import map is printed before module evaluation. Check the module API documentation for supported arguments and current behavior before adding a module, particularly if your code imports modules dynamically.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Best Value
Keep injected JavaScript secure and maintainable
JavaScript runs in the context of the page, so a snippet assembled from untrusted content can become a security problem. WordPress’s security guidance recommends validating and sanitizing input, escaping output, preferring WordPress APIs when possible, and keeping code updated. Choose escaping for the output context and escape as late as possible.
- Do not treat user-submitted values, database fields, or data from third parties as trusted executable code.
- Keep PHP data separate from JavaScript logic. If a value must enter inline JavaScript, validate it and apply context-appropriate escaping such as
esc_js(). - Use
esc_url()when outputting a URL into an HTML attribute; escaping a URL for HTML is not the same as making arbitrary JavaScript safe. - Use WordPress enqueue APIs rather than printing an untracked script tag when an enqueued asset can do the job.
- Update the code and its dependencies, and remove scripts that are no longer needed.
Troubleshoot a script that does not appear or run
| Symptom | Likely cause | What to check |
|---|---|---|
| No script tag appears in page source | The callback is attached to the wrong action, does not run for that page, or the theme does not call the relevant template function. | Confirm the front-end, admin, or login hook matches the target; inspect whether the theme calls wp_head() or wp_footer() for the requested placement. |
| Script tag appears but the file returns 404 | The URL does not match the asset’s actual location. | Open the script URL in the browser’s network tools and correct the path or file placement. |
| File loads but behavior fails | A dependency is missing, the code runs too early, or the browser reports a JavaScript error. | Check the browser console, declare registered dependencies, and choose placement or strategy that preserves the required execution order. |
| Changes do not appear after editing | A cached copy may still be served, or the version value was not changed. | Inspect the loaded URL and caching behavior; update the enqueue version as appropriate for the deployment. |
| A second enqueue seems to have no effect | The handle may already be registered with different parameters. | Use one consistent registration for a handle. The enqueue reference notes that enqueuing an already registered handle with different parameters does not replace the original registration. |
| Script appears on the wrong pages | The callback enqueues it too broadly. | Add a condition for the intended screen or page, and use the matching front-end, admin, or login action. |
When debugging, view the rendered page source and the browser’s network and console panels. Distinguish between a missing script tag, a failed file request, and code that loads but throws an error; each points to a different fix.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server; it captures a page rather than injecting JavaScript into WordPress. If your goal is to capture a rendered page after you have configured it, one GET request can return an image or PDF. See the ScreenshotNeo API documentation for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://wordpress.org -o shot.webpScreenshotNeo removes cookie/consent banners, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and responses include X-Page-Verdict and X-Billed headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Every feature is on every plan.
Sign up for 1,000 free screenshots a month with no card.
Frequently Asked Questions
Can I add JavaScript to WordPress without editing theme files?
Yes. A site-specific plugin can hold the enqueue callback, so the code is not tied to a theme file. The enqueue API remains the same.
Will adding JavaScript through an enqueue API make a script safe?
No. Enqueueing manages how WordPress includes a script; it does not make untrusted code or values safe. Validate input and escape output for its context.
Can I use the same script handle in a theme and a plugin?
Avoid reusing handles casually. Handles identify registered scripts, and a previously registered handle may not be replaced by another enqueue call with different parameters.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
