WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Function Reference/wp enqueue script

Contents


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 other 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
jQuery UI Core jquery-ui-core jquery
jQuery UI Widget jquery-ui-widget jquery
jQuery UI Mouse jquery-ui-mouse jquery
jQuery UI Accordion jquery-ui-accordion jquery
jQuery UI Autocomplete jquery-ui-autocomplete jquery
jQuery UI Slider jquery-ui-slider jquery
jQuery UI Progressbar jquery-ui-progressbar jquery
jQuery UI Tabs jquery-ui-tabs jquery
jQuery UI Sortable jquery-ui-sortable jquery
jQuery UI Draggable jquery-ui-draggable jquery
jQuery UI Droppable jquery-ui-droppable jquery
jQuery UI Selectable jquery-ui-selectable jquery
jQuery UI Position jquery-ui-position jquery
jQuery UI Datepicker jquery-ui-datepicker jquery
jQuery UI Tooltips jquery-ui-tooltip jquery
jQuery UI Resizable jquery-ui-resizable jquery
jQuery UI Dialog jquery-ui-dialog jquery
jQuery UI Button jquery-ui-button 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.
  • 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

Related

See also index of Function Reference and index of Template Tags.
This article is marked as in need of editing. You can help Codex by editing it.