Codex tools: Log in
Languages: English • Español • Русский • 中文(简体) • 한국어 • (Add your language)
Contents |
The safe and recommended method of adding JavaScript to a WordPress generated page is by using wp_enqueue_script(). This function includes the script if it hasn't already been included, and safely handles dependencies.
wp_enqueue_script(
$handle
,$src
,$deps
,$ver
,$in_footer
);
Use the wp_enqueue_scripts action to call this function, or admin_enqueue_scripts to call it on the admin side.
wp_head is run, even if it will be placed in the footer.
Note: This function will not work if it is called from a wp_head or wp_print_scripts actions, as the files need to be enqueued before those actions are run. See the Usage section for the correct hooks to use.
Please Note: It is not recommended that a theme force a 3rd party served JavaScript or CSS file by default, Doing so opens the users up to reliance upon a external host which is out of their control. A much better alternative is to use/recomend a Plugin such as Plugin: Use Google Libraries which automatically uses the Google-CDN served jQuery of the same version that WordPress uses this ultimately reduces breakage caused by Themes/Plugins which hardcode the file to use.
Suppose you want to use the CDN copy of jQuery instead of WordPress’s, add this code to your functions.php file.
<?php
function my_scripts_method() {
wp_deregister_script( 'jquery' );
wp_register_script( 'jquery', 'http://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js');
wp_enqueue_script( 'jquery' );
}
add_action('wp_enqueue_scripts', 'my_scripts_method');
?>
by using the wp_enqueue_scripts hook (instead of the init hook which many articles reference), we avoid registering the alternate jQuery on admin pages, which will cause post editing (amongst other things) to break after upgrades often.
<?php
function my_scripts_method() {
wp_enqueue_script('scriptaculous');
}
add_action('wp_enqueue_scripts', 'my_scripts_method'); // For use on the Front end (ie. Theme)
?>
The above example only loads the Scriptaculous library on the front end, If it was needed within the admin, you could use the admin_enqueue_scripts action instead, however this enqueues it on ALL admin pages, which often leads to plugin/core conflicts, ultimately breaking the WordPress admin experience. Instead, You should only load it on the individual pages you need it, See the Load scripts only on Plugin pages section for an example of that.
Add and load a new script that depends on Scriptaculous. This will cause WordPress to load Scriptaculous into the page before the new script.
<?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');
?>
Often JavaScript files included in Themes require another JavaScript file to be loaded before the theme's JavaScript file. WordPress offers an API for marking dependencies when registering a script. For example, the below theme requires jQuery for the custom_script JavaScript file:
<?php
function my_scripts_method() {
wp_enqueue_script(
'custom-script',
get_template_directory_uri() . '/js/custom_script.js',
array('jquery')
);
}
add_action('wp_enqueue_scripts', 'my_scripts_method');
?>
<?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() {
/* Register our plugin page */
$page = add_submenu_page( 'edit.php', // The parent page of this menu
__( 'My Plugin', 'myPlugin' ), // The Menu Title
__( 'My Plugin', 'myPlugin' ), // The Page title
'manage_options', // The capability required for access to this item
'my_plugin-options', // the slug to use for the page in the URL
'my_plugin_manage_menu' // The function to call to render the page
);
/* Using registered $page handle to hook script load */
add_action('admin_print_styles-' . $page, 'my_plugin_admin_styles');
}
function my_plugin_admin_styles() {
/*
* It will be called only on your plugin admin page, enqueue our script here
*/
wp_enqueue_script( 'my-plugin-script' );
}
function my_plugin_manage_menu() {
/* Output our admin page */
}
?>
Note: The jQuery library included with WordPress loads in "no conflict" mode. This is to prevent compatibility problems with other javascript libraries that WordPress can load.
In "no-confict" mode, the $ shortcut is not available and the longer jQuery is used. For example:
$(document).ready(function(){
$(#somefunction) ...
});
Becomes:
jQuery(document).ready(function(){
jQuery(#somefunction) ...
});
In order to use the default jQuery shortcut of $, you can use the following wrapper around your code:
jQuery(document).ready(function($) {
// $() will work as an alias for jQuery() inside of this function
});
That wrapper will cause your code to be executed when the page finishes loading, and the $ will work for calling jQuery. 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($) {
// $() will work as an alias for jQuery() inside of this function
})(jQuery);
| Script Name | Handle | Needed Dependency * |
|---|---|---|
| Scriptaculous Root | scriptaculous-root | |
| Scriptaculous Builder | scriptaculous-builder | |
| Scriptaculous Drag & Drop | scriptaculous-dragdrop | |
| Scriptaculous Effects | scriptaculous-effects | |
| Scriptaculous Slider | scriptaculous-slider | |
| Scriptaculous Sound | scriptaculous-sound | |
| Scriptaculous Controls | scriptaculous-controls | |
| Scriptaculous | scriptaculous | |
| Image Cropper | Image cropper (not used in core, see jcrop) | |
| Jcrop | Image copper | |
| 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 UI Core | jquery-ui-core (Att.: This is not the whole core incl. all core plugins. Just the base 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 Slider | jquery-ui-slider | 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 Datepicker | jquery-ui-datepicker | jquery |
| jQuery UI Resizable | jquery-ui-resizable | jquery |
| jQuery UI Dialog | jquery-ui-dialog | jquery |
| jQuery UI Button | jquery-ui-button | jquery |
| jQuery Schedule | schedule | jquery |
| jQuery Suggest | suggest | jquery |
| ThickBox | thickbox | |
| jQuery Hotkeys | jquery-hotkeys | jquery |
| Simple AJAX Code-Kit | sack | |
| QuickTags | quicktags | |
| Farbtastic (color picker) | farbtastic | jquery |
| ColorPicker (deprecated) | colorpicker | jquery |
| Tiny MCE | tiny_mce | |
| Prototype Framework | prototype | |
| Autosave | autosave | |
| WordPress AJAX Response | wp-ajax-response | |
| List Manipulation | wp-lists | |
| WP Common | common | |
| WP Editor | editor | |
| 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-repy | |
| Admin Gallery | admin-gallery | |
| Media Upload | media-upload | |
| Admin widgets | admin-widgets | |
| Word Count | word-count | |
| Theme Preview | theme-preview | |
| JSON for JS | json2 |
For a detailed list of names that can be used as $handle, see Notes on wp_register_script();.
The list is far from complete. For more details (a complete list of registered files) inspect the $GLOBALS['wp_scripts'] in the admin UI. Registered scripts might change per requested page.
* Dependencies not complete.
Since: 2.6 (BackPress version: r16)
wp_enqueue_script() is located in wp-includes/functions.wp-scripts.php.
