Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!Function Reference/wp enqueue script
Contents
Languages: English • Español • 日本語 • 한국어 • Русский • 中文(简体) • (Add your language)
Description
Links a script file to the generated page at the right time according to the script dependencies, if the script has not been already included and if all the dependencies have been registered. You could either link a script with a handle previously registered using the wp_register_script() function, or provide this function with all the parameters necessary to link a script.
This is the recommended method of linking JavaScript to a WordPress generated page.
Usage
<?php wp_enqueue_script( $handle, $src, $deps, $ver, $in_footer ); ?>
See Notes for information about what action hooks should be used to call the function.
Parameters
- $handle
- (string) (required) Name used as a handle for the script. As a special case, if the string contains a '?' character, the preceding part of the string refers to the registered handle, and the succeeding part is appended to the URL as a query string. A version must be used with this special case.
- Default: None
- $src
- (string) (optional) URL to the script, e.g. http://example.com/wp-content/themes/my-theme/my-theme-script.js. You should never hardcode URLs to local scripts. To get a proper URL to local scripts, use plugins_url() for plugins and get_template_directory_uri() for themes. Remote scripts can be specified with a protocol-agnostic URL, e.g. //otherdomain.com/js/their-script.js. This parameter is only required when the script with the given $handle has not been already registered using wp_register_script(). See Default Scripts Included and Registered by WordPress.
- Default: false
- $deps
- (array) (optional) Array of the handles of all the registered scripts that this script depends on, that is the scripts that must be loaded before this script. This parameter is only required when the script with the given $handle has not been already registered using wp_register_script(). Default handles are all in lower case.
- Default: array()
- $ver
- (string) (optional) String specifying the script version number, if it has one, which is concatenated to the end of the path as a query string. If no version is specified or set to false, then WordPress automatically adds a version number equal to the current version of WordPress you are running. If set to null no version is added. This parameter is used to ensure that the correct version is sent to the client regardless of caching, and so should be included if a version number is available and makes sense for the script.
- Default: false
- $in_footer
- (boolean) (optional) Normally, scripts are placed in <head> of the HTML document. If this parameter is true, the script is placed before the </body> end tag. This requires the theme to have the wp_footer() template tag in the appropriate place.
- Default: false
Return Values
- (void)
- This function does not return a value.
Examples
Using a Hook
Scripts and styles from a single action hook
/**
* Proper way to enqueue scripts and styles
*/
function theme_name_scripts() {
wp_enqueue_style( 'style-name', get_stylesheet_uri() );
wp_enqueue_script( 'script-name', get_template_directory_uri() . '/js/example.js', array(), '1.0.0', true );
}
add_action( 'wp_enqueue_scripts', 'theme_name_scripts' );
Link the script.aculo.us Library
The following is an example of basic usage which links the script.aculo.us library already included and registered by WordPress with the scriptaculous handle.
<?php
function my_scripts_method() {
wp_enqueue_script( 'scriptaculous' );
}
add_action( 'wp_enqueue_scripts', 'my_scripts_method' ); // wp_enqueue_scripts action hook to link only on the front-end
?>
The above example links the script.aculo.us library only on the front-end. If the library was needed within the administration screens, you could use the admin_enqueue_scripts action hook instead, however, this would enqueue it on all the administration screens, which often leads to plugin/core conflicts, ultimately breaking the WordPress administration screens experience. Instead, you should only link it on the individual screens you need it, see the Link Scripts Only on a Plugin Administration Screen section for an example of that.
Link a Theme Script Which Depends on jQuery
JavaScript files included in themes often require another JavaScript file to be loaded in advance to use its functions or variables. Using the $deps parameter, the wp_enqueue_script() and wp_register_script() functions allows you to mark dependencies when registering a new script. This will cause WordPress to automatically link these dependencies to the HTML page before the new script is linked. If the handles of these dependencies are not registered, WordPress will not link the new script. This example requires the jQuery library for the custom_script.js theme script:
<?php
function my_scripts_method() {
wp_enqueue_script(
'custom-script',
get_stylesheet_directory_uri() . '/js/custom_script.js',
array( 'jquery' )
);
}
add_action( 'wp_enqueue_scripts', 'my_scripts_method' );
?>
Link a Plugin Script That Depends on script.aculo.us
This example is intended to be used within a plugin file to register and link a new plugin script that depends on the script.aculo.us library. See the example above for information about dependencies.
<?php
function my_scripts_method() {
wp_enqueue_script(
'newscript',
plugins_url( '/js/newscript.js' , __FILE__ ),
array( 'scriptaculous' )
);
}
add_action( 'wp_enqueue_scripts', 'my_scripts_method' );
?>
Link Scripts Only on a Plugin Administration Screen
This example links a script only on a specific administration screen, as opposed to the scenario described in the paragraph below the code of the first example.
<?php
add_action( 'admin_init', 'my_plugin_admin_init' );
add_action( 'admin_menu', 'my_plugin_admin_menu' );
function my_plugin_admin_init() {
/* Register our script. */
wp_register_script( 'my-plugin-script', plugins_url( '/script.js', __FILE__ ) );
}
function my_plugin_admin_menu() {
/* Add our plugin submenu and administration screen */
$page_hook_suffix = add_submenu_page( 'edit.php', // The parent page of this submenu
__( 'My Plugin', 'myPlugin' ), // The submenu title
__( 'My Plugin', 'myPlugin' ), // The screen title
'manage_options', // The capability required for access to this submenu
'my_plugin-options', // The slug to use in the URL of the screen
'my_plugin_manage_menu' // The function to call to display the screen
);
/*
* Use the retrieved $page_hook_suffix to hook the function that links our script.
* This hook invokes the function only on our plugin administration screen,
* see: http://codex.wordpress.org/Administration_Menus#Page_Hook_Suffix
*/
add_action('admin_print_scripts-' . $page_hook_suffix, 'my_plugin_admin_scripts');
}
function my_plugin_admin_scripts() {
/* Link our already registered script to a page */
wp_enqueue_script( 'my-plugin-script' );
}
function my_plugin_manage_menu() {
/* Display our administration screen */
}
?>
Load a Script from a Child Theme without Dependencies
Register and enqueue the script in the same callback function with no dependencies, in the footer. See wp_register_script() for details. In this example, google_analytics_object.js is the Google Analytics tracking code (provided by Google) in a file.
<?php
add_action( 'wp_enqueue_scripts', 'child_add_scripts' );
/**
* Register and enqueue a script that does not depend on a JavaScript library.
*/
function child_add_scripts() {
wp_register_script(
'google-analytics',
get_stylesheet_directory_uri() . '/google_analytics_object.js',
false,
'1.0',
true
);
wp_enqueue_script( 'google-analytics' );
}
jQuery noConflict Wrappers
The jQuery library included with WordPress is set to the noConflict() mode (see wp-includes/js/jquery/jquery.js). This is to prevent compatibility problems with other JavaScript libraries that WordPress can link.
In the noConflict() mode, the global $ shortcut for jQuery is not available, so you can still use:
jQuery(document).ready(function(){
jQuery(#somefunction) ...
});
but the following will either throw an error, or use the $ shortcut as assigned by another library.
$(document).ready(function(){
$(#somefunction) ...
});
However, if you really like the short $ instead of jQuery, you can use the following wrapper around your code:
jQuery(document).ready(function($) {
// Inside of this function, $() will work as an alias for jQuery()
// and other libraries also using $ will not be accessible under this shortcut
});
That wrapper will cause your code to be executed when the DOM is fully constructed. If, for some reason, you want your code to execute immediately instead of waiting for the DOM ready event, then you can use this wrapper method instead:
(function($) {
// Inside of this function, $() will work as an alias for jQuery()
// and other libraries also using $ will not be accessible under this shortcut
})(jQuery);
Alternatively, you can always reasign jQuery to another shortcut of your choice and leave the $ shorcut to other libraries:
var $j = jQuery;
Default Scripts Included and Registered by WordPress
By default, WordPress installation includes many popular scripts commonly used by web developers besides the scripts used by WordPress itself. Some of them are listed in the table below.
For a detailed list of names that can be used in place of the $handle parameter, see Handles and Their Script Paths Registered by WordPress.
Note that in Version 3.5, WordPress changed its naming convention for minified scripts and styles. Before, minified scripts and styles had the .js and .css extensions, unminified had .dev.js and .dev.css. However, following the change, the extensions are .min.js and .min.css for minified files, .js and .css for unminified, respectively.
| Script Name | Handle | Needed Dependency * |
|---|---|---|
| Image Cropper | Image cropper (not used in core, see jcrop) | |
| Jcrop | jcrop | |
| SWFObject | swfobject | |
| SWFUpload | swfupload | |
| SWFUpload Degrade | swfupload-degrade | |
| SWFUpload Queue | swfupload-queue | |
| SWFUpload Handlers | swfupload-handlers | |
| jQuery | jquery | json2 (for AJAX calls) |
| jQuery Form | jquery-form | jquery |
| jQuery Color | jquery-color | jquery |
| jQuery Masonry | jquery-masonry | jquery |
| Masonry (native Javascript) | masonry | |
| jQuery UI Core | jquery-ui-core | jquery |
| jQuery UI Widget | jquery-ui-widget | jquery |
| jQuery UI Accordion | jquery-ui-accordion | jquery |
| jQuery UI Autocomplete | jquery-ui-autocomplete | jquery |
| jQuery UI Button | jquery-ui-button | jquery |
| jQuery UI Datepicker | jquery-ui-datepicker | jquery |
| jQuery UI Dialog | jquery-ui-dialog | jquery |
| jQuery UI Draggable | jquery-ui-draggable | jquery |
| jQuery UI Droppable | jquery-ui-droppable | jquery |
| jQuery UI Menu | jquery-ui-menu | jquery |
| jQuery UI Mouse | jquery-ui-mouse | jquery |
| jQuery UI Position | jquery-ui-position | jquery |
| jQuery UI Progressbar | jquery-ui-progressbar | jquery |
| jQuery UI Selectable | jquery-ui-selectable | jquery |
| jQuery UI Resizable | jquery-ui-resizable | jquery |
| jQuery UI Selectmenu | jquery-ui-selectmenu | jquery |
| jQuery UI Sortable | jquery-ui-sortable | jquery |
| jQuery UI Slider | jquery-ui-slider | jquery |
| jQuery UI Spinner | jquery-ui-spinner | jquery |
| jQuery UI Tooltips | jquery-ui-tooltip | jquery |
| jQuery UI Tabs | jquery-ui-tabs | jquery |
| jQuery UI Effects | jquery-effects-core | jquery |
| jQuery UI Effects - Blind | jquery-effects-blind | jquery-effects-core |
| jQuery UI Effects - Bounce | jquery-effects-bounce | jquery-effects-core |
| jQuery UI Effects - Clip | jquery-effects-clip | jquery-effects-core |
| jQuery UI Effects - Drop | jquery-effects-drop | jquery-effects-core |
| jQuery UI Effects - Explode | jquery-effects-explode | jquery-effects-core |
| jQuery UI Effects - Fade | jquery-effects-fade | jquery-effects-core |
| jQuery UI Effects - Fold | jquery-effects-fold | jquery-effects-core |
| jQuery UI Effects - Highlight | jquery-effects-highlight | jquery-effects-core |
| jQuery UI Effects - Pulsate | jquery-effects-pulsate | jquery-effects-core |
| jQuery UI Effects - Scale | jquery-effects-scale | jquery-effects-core |
| jQuery UI Effects - Shake | jquery-effects-shake | jquery-effects-core |
| jQuery UI Effects - Slide | jquery-effects-slide | jquery-effects-core |
| jQuery UI Effects - Transfer | jquery-effects-transfer | jquery-effects-core |
| MediaElement.js (WP 3.6+) | wp-mediaelement | jquery |
| jQuery Schedule | schedule | jquery |
| jQuery Suggest | suggest | jquery |
| ThickBox | thickbox | |
| jQuery HoverIntent | hoverIntent | jquery |
| jQuery Hotkeys | jquery-hotkeys | jquery |
| Simple AJAX Code-Kit | sack | |
| QuickTags | quicktags | |
| Iris (Colour picker) | iris | jquery |
| Farbtastic (deprecated) | farbtastic | jquery |
| ColorPicker (deprecated) | colorpicker | jquery |
| Tiny MCE | tiny_mce | |
| Autosave | autosave | |
| WordPress AJAX Response | wp-ajax-response | |
| List Manipulation | wp-lists | |
| WP Common | common | |
| WP Editor | editorremov | |
| WP Editor Functions | editor-functions | |
| AJAX Cat | ajaxcat | |
| Admin Categories | admin-categories | |
| Admin Tags | admin-tags | |
| Admin custom fields | admin-custom-fields | |
| Password Strength Meter | password-strength-meter | |
| Admin Comments | admin-comments | |
| Admin Users | admin-users | |
| Admin Forms | admin-forms | |
| XFN | xfn | |
| Upload | upload | |
| PostBox | postbox | |
| Slug | slug | |
| Post | post | |
| Page | page | |
| Link | link | |
| Comment | comment | |
| Threaded Comments | comment-reply | |
| Admin Gallery | admin-gallery | |
| Media Upload | media-upload | |
| Admin widgets | admin-widgets | |
| Word Count | word-count | |
| Theme Preview | theme-preview | |
| JSON for JS | json2 | |
| Plupload Core | plupload | |
| Plupload All Runtimes | plupload-all | |
| Plupload HTML4 | plupload-html4 | |
| Plupload HTML5 | plupload-html5 | |
| Plupload Flash | plupload-flash | |
| Plupload Silverlight | plupload-silverlight | |
| Underscore js | underscore | |
| Backbone js | backbone |
| Removed from Core | |||
|---|---|---|---|
| Script Name | Handle | Removed Version | Replaced With |
| Scriptaculous Root | scriptaculous-root | WP 3.5 | Google Version |
| Scriptaculous Builder | scriptaculous-builder | WP 3.5 | Google Version |
| Scriptaculous Drag & Drop | scriptaculous-dragdrop | WP 3.5 | Google Version |
| Scriptaculous Effects | scriptaculous-effects | WP 3.5 | Google Version |
| Scriptaculous Slider | scriptaculous-slider | WP 3.5 | Google Version |
| Scriptaculous Sound | scriptaculous-sound | WP 3.5 | Google Version |
| Scriptaculous Controls | scriptaculous-controls | WP 3.5 | Google Version |
| Scriptaculous | scriptaculous | WP 3.5 | Google Version |
| Prototype Framework | prototype | WP 3.5 | Google Version |
The list is far from complete. For a complete list of registered files inspect $GLOBALS['wp_scripts'] in the admin UI. Registered scripts might change per requested page.
* The listed dependencies are not complete.
Notes
- The function should be called using the wp_enqueue_scripts action hook if you want to call it on the front-end of the site, like in the examples above. To call it on the administration screens, use the admin_enqueue_scripts action hook. For the login screen, use the login_enqueue_scripts action hook. Calling it outside of an action hook can lead to problems, see the ticket #11526 for details.
- Prior to Version 3.3, the function will have no effect if it is called using the wp_head or wp_print_scripts action hooks or later, as this is too late to enqueue the files even if the $in_footer parameter is set to true.
- As of Version 3.3, the function can be called mid-page (before the wp_footer() template tag) or using the wp_head action hook. This will place the script in the footer as if the $in_footer parameter was set to true.
- If you try to register or enqueue an already registered handle with different parameters, the new parameters will be ignored. Instead, use wp_deregister_script() and register the script again with the new parameters.
- jQuery UI Effects is not included with the jquery-ui-core handle.
- This function relies on the use of wp_head() and wp_footer() by the active theme. This means that it may not work with a few very old themes that do not call these functions. This is useful to keep in mind when debugging ancient themes.
- Uses: WP_Scripts::add(), WP_Scripts::add_data() and WP_Scripts::enqueue().
- Uses global: (unknown type) $wp_scripts.
Change Log
- Since: 2.6 (BackPress version: r16)
Source File
wp_enqueue_script() is located in wp-includes/functions.wp-scripts.php.
Resources
- Best practice for adding JavaScript code to WordPress plugins
- How To: Load Javascript With Your WordPress Plugin
- How to load JavaScript in WordPress plugins
- Using JavaScript and CSS with your WordPress Plugin
- Using Javascript libraries with your Wordpress plugin or theme
- 5 Tips For Using jQuery with WordPress
- How to Include CSS and JavaScript Conditionally, and Only When Needed by the Posts
- Make Your WordPress Plugins Use a Different Version of a Bundled JavaScript Library Replacing built-in JavaScript libraries is usually a bad idea. Do this only on sites you administer personally.
- How to load JavaScript like a WordPress Master Highly recommended.
- How to disable scripts and styles
- Loading javascript on the frontend with your WordPress plugin
- JavaScript Tips and Tricks for WordPress 3.x
- Developing for WordPress's customized version of ThickBox
- WordPress Script Registration Generator
Related
Enqueue Scripts
- wp_register_script()
- wp_deregister_script()
- wp_enqueue_script()
- wp_dequeue_script()
- wp_script_is()
- wp_localize_script()
- wp_enqueue_media()
Enqueue Styles
- wp_register_style()
- wp_deregister_style()
- wp_enqueue_style()
- wp_dequeue_style()
- wp_style_is()
- wp_add_inline_style()
Front-End Hooks
Admin Hooks
Login Hooks