Including CSS & JavaScript

When you’re creating your theme, you may want to create additional stylesheets or JavaScript files. However, remember that a WordPress website will not just have your theme active, it will also be using many different plugins. So that everything works harmoniously, it’s important that theme and plugins load scripts and stylesheets using the standard WordPress method. This will ensure the site remains efficient and that there are no incompatibility issues.

Adding scripts and styles to WordPress is a fairly simple process.   Essentially, you will create a function that will enqueue all of your scripts and styles. When enqueuing a script or stylesheet, WordPress creates a handle and path to find your file and any dependencies it may have (like jQuery) and then you will use a hook that will insert your scripts and stylesheets.

Enqueuing Scripts and Styles Enqueuing Scripts and Styles

The proper way to add scripts and styles to your theme is to enqueue them in the functions.php files. The style.css file is required in all themes, but it may be necessary to add other files to extend the functionality of your theme.

Tip: WordPress includes a number of JavaScript files as part of the software package, including commonly used libraries such as jQuery. Before adding your own JavaScript, check to see if you can make use of an included library.

The basics are:

  1. Enqueue the script or style using wp_enqueue_script() or wp_enqueue_style()

Stylesheets Stylesheets

Your CSS stylesheets are used to customize the presentation of your theme. A stylesheet is also the file where information about your theme is stored. For this reason, the style.css file is required in every theme.

Rather then loading the stylesheet in your header.php file, you should load it in using wp_enqueue_style. In order to load your main stylesheet, you can enqueue it in functions.php

To enqueue style.css

wp_enqueue_style( 'style', get_stylesheet_uri() );

This will look for a stylesheet named “style” and load it.

The basic function for enqueuing a style is:

wp_enqueue_style( $handle, $src, $deps, $ver, $media );

You can include these parameters:

  • $handle is simply the name of the stylesheet.
  • $src is where it is located. The rest of the parameters are optional.
  • $deps refers to whether or not this stylesheet is dependent on another stylesheet. If this is set, this stylesheet will not be loaded unless its dependent stylesheet is loaded first.
  • $ver sets the version number.
  • $media can specify which type of media to load this stylesheet in, such as ‘all’, ‘screen’, ‘print’ or ‘handheld.’

So if you wanted to load a stylesheet named “slider.css” in a folder named “CSS” in you theme’s root directory, you would use:

wp_enqueue_style( 'slider', get_template_directory_uri() . '/css/slider.css',false,'1.1','all');

Top ↑

Scripts Scripts

Any additional JavaScript files required by a theme should be loaded using wp_enqueue_script. This ensures proper loading and caching, and allows the use conditional tags to target specific pages. These are optional.

wp_enqueue_script uses a similar syntax to wp_enqueue_style.

Enqueue your script:

wp_enqueue_script( $handle, $src, $deps, $ver, $in_footer);
  • $handle is the name for the script.
  • $src defines where the script is located.
  • $deps is an array that can handle any script that your new script depends on, such as jQuery.
  • $ver lets you list a version number.
  • $in_footer is a boolean parameter (true/false) that allows you to place your scripts in the footer of your HTML document rather then in the header, so that it does not delay the loading of the DOM tree.

Your enqueue function may look like this:

wp_enqueue_script( 'script', get_template_directory_uri() . '/js/script.js', array ( 'jquery' ), 1.1, true);

Top ↑

The Comment Reply Script The Comment Reply Script

WordPress comments have quite a bit of functionality in them right out of the box, including threaded comments and enhanced comment forms. In order for comments to work properly, they require some JavaScript. However, since there are certain options that need to be defined within this JavaScript, the comment-reply script should be added to every theme that uses comments.

The proper way to include comment reply is to use conditional tags to check if certain conditions exist, so that the script isn’t being loaded unnecessarily. For instance, you can only load scripts on single post pages using is_singular, and check to make sure that “Enable threaded comments” is selected by the user. So you can set up a function like:

if ( is_singular() && comments_open() && get_option( 'thread_comments' ) ) {
	wp_enqueue_script( 'comment-reply' );
}

If comments are enabled by the user, and we are on a post page, then the comment reply script will be loaded. Otherwise, it will not.

Top ↑

Combining Enqueue Functions Combining Enqueue Functions

It is best to combine all enqueued scripts and styles into a single function, and then call them using the wp_enqueue_scripts action. This function and action should be located somewhere below the initial setup (performed above).

function add_theme_scripts() {
  wp_enqueue_style( 'style', get_stylesheet_uri() );

  wp_enqueue_style( 'slider', get_template_directory_uri() . '/css/slider.css', array(), '1.1', 'all');

  wp_enqueue_script( 'script', get_template_directory_uri() . '/js/script.js', array ( 'jquery' ), 1.1, true);

    if ( is_singular() && comments_open() && get_option( 'thread_comments' ) ) {
      wp_enqueue_script( 'comment-reply' );
    }
}
add_action( 'wp_enqueue_scripts', 'add_theme_scripts' );

Top ↑

Default Scripts Included and Registered by WordPress Default Scripts Included and Registered by WordPress

By default, WordPress includes many popular scripts commonly used by web developers, as well as the scripts used by WordPress itself. Some of them are listed in the table below:

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. You can find a full list of included files in wp-includes/script-loader.php.