WordPress.org

Ready to get started?Download WordPress

Codex

Function Reference/wp register script

Contents

Description

Registers a script file in WordPress to be linked to a page later using the wp_enqueue_script() function, which safely handles the script dependencies.

Scripts that have been pre-registered using wp_register_script() do not need to be manually enqueued using wp_enqueue_script() if they are listed as a dependency of another script that is enqueued. WordPress will automatically include the registered script before it includes the enqueued script that lists the registered script's handle as a dependency. See the Notes for more information.

Usage

<?php wp_register_script$handle$src$deps$ver$in_footer ); ?> See Notes for information about what action hooks should be used to call the function as well as some insights on the rationale for using this function.

Parameters

$handle
(string) (required) Name of the script. Should be unique as it is used as a handle for later use with wp_enqueue_script().
Default: None
$src
(string) (required) 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.
Default: None
$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. These scripts will automatically be enqueued when this script is enqueued with wp_enqueue_script(). Set false if there are no dependencies.
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 the <head> section. If this parameter is true the script is placed at the bottom of the <body>. This requires the theme to have the wp_footer() hook in the appropriate place. Note that you have to enqueue your script before wp_head is run, even if it will be placed in the footer. (New in WordPress 2.8)
Default: false

Return Values

(void) 
This function does not return a value.

Examples

See Examples on wp_enqueue_script().

Handles and Their Script Paths Registered by WordPress

By default, WordPress installation includes many popular scripts commonly used by web developers besides the scripts used by WordPress itself. Below is a list of the handles and paths of these scripts. "This list has been updated for 3.8." Source: wp-includes/script-loader.php.

Handle Path in WordPress
utils /wp-includes/js/utils.js
common /wp-admin/js/common.js
sack /wp-includes/js/tw-sack.js
quicktags /wp-includes/js/quicktags.js
colorpicker /wp-includes/js/colorpicker.js
editor /wp-admin/js/editor.js
wp-fullscreen /wp-admin/js/wp-fullscreen.js
wp-ajax-response /wp-includes/js/wp-ajax-response.js
wp-pointer /wp-includes/js/wp-pointer.js
autosave /wp-includes/js/autosave.js
heartbeat /wp-includes/js/heartbeat.js
wp-auth-check /wp-includes/js/wp-auth-check.js
wp-lists /wp-includes/js/wp-lists.js
 
prototype external: //ajax.googleapis.com/ajax/libs/prototype/1.7.1.0/prototype.js
scriptaculous-root external: //ajax.googleapis.com/ajax/libs/prototype/1.7.1.0/prototype.js
scriptaculous-builder external: //ajax.googleapis.com/ajax/libs/prototype/1.7.1.0/builder.js
scriptaculous-dragdrop external: //ajax.googleapis.com/ajax/libs/prototype/1.7.1.0/dragdrop.js
scriptaculous-effects external: //ajax.googleapis.com/ajax/libs/prototype/1.7.1.0/effects.js
scriptaculous-slider external: //ajax.googleapis.com/ajax/libs/prototype/1.7.1.0/slider.js
scriptaculous-sound external: //ajax.googleapis.com/ajax/libs/prototype/1.7.1.0/sound.js
scriptaculous-controls external: //ajax.googleapis.com/ajax/libs/prototype/1.7.1.0/controls.js
scriptaculous scriptaculous-dragdrop, scriptaculous-slider, scriptaculous-controls
cropper /wp-includes/js/crop/cropper.js
 
jquery (v1.10.2 as of WP 3.8) jquery-core, jquery-migrate
jquery-core /wp-includes/js/jquery/jquery.js
jquery-migrate /wp-includes/js/jquery/jquery-migrate.js (v1.10.2 as of WP 3.8)
jquery-ui-core /wp-includes/js/jquery/ui/jquery.ui.core.min.js
jquery-effects-core /wp-includes/js/jquery/ui/jquery.ui.effect.min.js
jquery-effects-blind /wp-includes/js/jquery/ui/jquery.ui.effect-blind.min.js
jquery-effects-bounce /wp-includes/js/jquery/ui/jquery.ui.effect-bounce.min.js
jquery-effects-clip /wp-includes/js/jquery/ui/jquery.ui.effect-clip.min.js
jquery-effects-drop /wp-includes/js/jquery/ui/jquery.ui.effect-drop.min.js
jquery-effects-explode /wp-includes/js/jquery/ui/jquery.ui.effect-explode.min.js
jquery-effects-fade /wp-includes/js/jquery/ui/jquery.ui.effect-fade.min.js
jquery-effects-fold /wp-includes/js/jquery/ui/jquery.ui.effect-fold.min.js
jquery-effects-highlight /wp-includes/js/jquery/ui/jquery.ui.effect-highlight.min.js
jquery-effects-pulsate /wp-includes/js/jquery/ui/jquery.ui.effect-pulsate.min.js
jquery-effects-scale /wp-includes/js/jquery/ui/jquery.ui.effect-scale.min.js
jquery-effects-shake /wp-includes/js/jquery/ui/jquery.ui.effect-shake.min.js
jquery-effects-slide /wp-includes/js/jquery/ui/jquery.ui.effect-slide.min.js
jquery-effects-transfer /wp-includes/js/jquery/ui/jquery.ui.effect-transfer.min.js
jquery-ui-accordion /wp-includes/js/jquery/ui/jquery.ui.accordion.min.js
jquery-ui-autocomplete /wp-includes/js/jquery/ui/jquery.ui.autocomplete.min.js
jquery-ui-button /wp-includes/js/jquery/ui/jquery.ui.button.min.js
jquery-ui-datepicker /wp-includes/js/jquery/ui/jquery.ui.datepicker.min.js
jquery-ui-dialog /wp-includes/js/jquery/ui/jquery.ui.dialog.min.js
jquery-ui-draggable /wp-includes/js/jquery/ui/jquery.ui.draggable.min.js
jquery-ui-droppable /wp-includes/js/jquery/ui/jquery.ui.droppable.min.js
jquery-ui-menu /wp-includes/js/jquery/ui/jquery.ui.menu.min.js
jquery-ui-mouse /wp-includes/js/jquery/ui/jquery.ui.mouse.min.js
jquery-ui-position /wp-includes/js/jquery/ui/jquery.ui.position.min.js
jquery-ui-progressbar /wp-includes/js/jquery/ui/jquery.ui.progressbar.min.js
jquery-ui-resizable /wp-includes/js/jquery/ui/jquery.ui.resizable.min.js
jquery-ui-selectable /wp-includes/js/jquery/ui/jquery.ui.selectable.min.js
jquery-ui-slider /wp-includes/js/jquery/ui/jquery.ui.slider.min.js
jquery-ui-sortable /wp-includes/js/jquery/ui/jquery.ui.sortable.min.js
jquery-ui-spinner /wp-includes/js/jquery/ui/jquery.ui.spinner.min.js
jquery-ui-tabs /wp-includes/js/jquery/ui/jquery.ui.tabs.min.js
jquery-ui-tooltip /wp-includes/js/jquery/ui/jquery.ui.tooltip.min.js
jquery-ui-widget /wp-includes/js/jquery/ui/jquery.ui.widget.min.js
jquery-form /wp-includes/js/jquery/jquery.form.js
jquery-color /wp-includes/js/jquery/jquery.color.min.js
suggest /wp-includes/js/jquery/suggest.js
schedule /wp-includes/js/jquery/jquery.schedule.js
jquery-query /wp-includes/js/jquery/jquery.query.js
jquery-serialize-object /wp-includes/js/jquery/jquery.serialize-object.js
jquery-hotkeys /wp-includes/js/jquery/jquery.hotkeys.js
jquery-table-hotkeys /wp-includes/js/jquery/jquery.table-hotkeys.js
jquery-touch-punch /wp-includes/js/jquery/jquery.ui.touch-punch.js
jquery-masonry /wp-includes/js/jquery/jquery.masonry.min.js
 
thickbox /wp-includes/js/thickbox/thickbox.js
jcrop /wp-includes/js/jcrop/jquery.Jcrop.js
swfobject /wp-includes/js/swfobject.js
plupload /wp-includes/js/plupload/plupload.js
plupload-html5 wp-includes/js/plupload/plupload.html5.js
plupload-flash /wp-includes/js/plupload/plupload.flash.js"
plupload-silverlight /wp-includes/js/plupload/plupload.silverlight.js
plupload-html4 /wp-includes/js/plupload/plupload.html4.js
plupload-all plupload, plupload-html5, plupload-flash, plupload-silverlight, plupload-html4
plupload-handlers /wp-includes/js/plupload/handlers.js
wp-plupload /wp-includes/js/plupload/wp-plupload.js
swfupload /wp-includes/js/swfupload/swfupload.js
swfupload-swfobject /wp-includes/js/swfupload/plugins/swfupload.swfobject.js
swfupload-queue /wp-includes/js/swfupload/plugins/swfupload.queue.js
swfupload-speed /wp-includes/js/swfupload/plugins/swfupload.speed.js
swfupload-all /wp-includes/js/swfupload/swfupload-all.js
swfupload-handlers /wp-includes/js/swfupload/handlers.js
comment-reply /wp-includes/js/comment-reply.js
json2 /wp-includes/js/json2.js
underscore /wp-includes/js/underscore.min.js
backbone /wp-includes/js/backbone.min.js
wp-util /wp-includes/js/wp-util.js
wp-backbone /wp-includes/js/wp-backbone.js
revisions /wp-admin/js/revisions.js
imgareaselect /wp-includes/js/imgareaselect/jquery.imgareaselect.js
mediaelement /wp-includes/js/mediaelement/mediaelement-and-player.min.js
wp-mediaelement /wp-includes/js/mediaelement/wp-mediaelement.js
zxcvbn-async /wp-includes/js/zxcvbn-async.js
password-strength-meter /wp-admin/js/password-strength-meter.js
user-profile /wp-admin/js/user-profile.js
user-suggest /wp-admin/js/user-suggest.js
admin-bar /wp-includes/js/admin-bar.js
wplink /wp-includes/js/wplink.js
wpdialogs /wp-includes/js/tinymce/plugins/wpdialogs/js/wpdialog.js
wpdialogs-popup /wp-includes/js/tinymce/plugins/wpdialogs/js/popup.js
word-count /wp-admin/js/word-count.js
media-upload /wp-admin/js/media-upload.js
hoverIntent /wp-includes/js/hoverIntent.js
customize-base /wp-includes/js/customize-base.js
customize-loader
customize-preview
customize-controls
accordion
shortcode
media-models
media-views
media-editor
mce-view
admin-tags
admin-comments
xfn
postbox
post
link
comment
admin-gallery
admin-widgets
theme
theme-install
inline-edit-post
inline-edit-tax
plugin-install
farbtastic
iris
wp-color-picker
dashboard
list-revisions
media
image-edit
set-post-thumbnail
nav-menu
custom-header
custom-background
media-gallery
svg-painter

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. 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. Also see Notes on wp_enqueue_script() for more details about the proper hooks.
  • 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() and WP_Scripts::add_data().
  • Uses global: (unknown type) $wp_scripts.

Usage Rationale

  • Technically, you never have to register anything if you don't want to. The register functions are there and can be valuable if you want a central location that defines scripts and styles that will be used in your plugin/theme. You can then simply use the enqueue functions while referring to just the handle in order to enqueue the script or style for inclusion in the head.
  • If the handle of a registered script is listed in the $deps array of dependencies of another script that is enqueued with wp_enqueue_script(), that script will be automatically loaded prior to loading the enqueued script. This greatly simplifies the process of ensuring that a script has all the dependencies it needs. See below for a simple example.
  • So, the main purpose of the register functions is to allow you to simplify your code by removing the need to duplicate code if you enqueue the same script or style in more than one section of code. The benefits of this are many and probably don't need to be listed here.

Example of Automatic Dependency Loading

This example demonstrates how a registered script is automatically loaded when listed as the dependency of an enqueued script:

// Always use wp_enqueue_scripts action hook to both enqueue and register scripts
add_action( 'wp_enqueue_scripts', 'enqueue_and_register_my_scripts' );

function enqueue_and_register_my_scripts(){

    // Use `get_stylesheet_directoy_uri() if your script is inside your theme or child theme.
    wp_register_script( 'my-script', get_stylesheet_directory_uri() . '/js/my-script.js' );

    // Let's enqueue a script only to be used on a specific page of the site
    if ( is_page( 'careers' ) ){

        // Enqueue a script that has both jQuery (automatically registered by WordPress)
        // and my-script (registered earlier) as dependencies.
        wp_enqueue_script( 'my-careers-script', get_stylesheet_directory_uri() . '/js/my-careers-script.js', array( 'jquery', 'my-script' ) );
    }
}

Note how, in the example above, `my-script.js` does not actually have to be enqueued. It is automatically loaded before `my-careers-script.js` by virtue of the fact that it was registered.

It's also interesting to note that, given how the `wp_enqueue_scripts` action works, the order in which scripts are enqueued or registered is quite inconsequential. Really.

Change Log

  • Since: 2.6 (BackPress version: r16)

Source File

wp_register_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.