Register & enqueue your WordPress theme’s scripts and styles The Right Way™

If you’ve been building themes for a while, and happen to have come from a HTML/CSS background, you’ll remember the days when you hardcoded calls to your theme’s linked stylesheets and JavaScripts directly in the <head>. While this still works just fine, there’s a WordPress way of doing this: by enqueuing the scripts and styles from functions.php.

Enqueueing the scripts and styles means you can granularly define where the file is loaded i.e. in the header or in the footer, whether its dependent upon one or multiple other files therefore needs to get called after its dependency, etc.

Defining the function

To enqueue CSS stylesheets, we’ll use wp_enqueue_style() and to enqueue the JavaScripts, we’ll use wp_enqueue_script().

function butter_scripts_and_styles() {
  // enqueue the main style.css stylesheet
  wp_enqueue_style( 'main-styles', get_stylesheet_uri() );
  
  // enqueue a stylesheet that depends on the main stylesheet
  wp_enqueue_style( 'typography-styles', get_template_directory_uri() . '/css/typography.css', array( 'main-styles'), '1.0' );
  
  // enqueue main JavaScript file
  wp_enqueue_script( 'butter-main-scripts', get_template_directory_uri() . '/js/main.js', array( 'jquery' ), '1.0', true );
}
add_action( 'wp_enqueue_scripts', 'butter_scripts_and_styles' );

Note that the wp_enqueue_style() accepts 5 parameters: $handle, $src, $deps, $ver, and $media. For the typography.css stylesheet, for example, note that we’re including the previously enqueued main-styles as a dependency and we’re also versioning the stylesheet.

The main.js file is dependent upon jQuery. The WordPress way nowadays is not to deregister the WordPress provided version of jQuery and register our desired version. If a script depends on jQuery, as ours does, WordPress will load the core-provided version for us.

Also note that by specifying ‘true’ for the $in_footer parameter of wp_enqueue_script(), we’re instructing WordPress to load this script in the footer as opposed to the header.

To boost page-load speeds, its best to load your JavaScripts in the footer. So as much as possible set the $in_footer in the wp_enqueue_script() to ‘true’ unless its for a file like modernizr.js that needs to load first at the top of the page.

Conditional Enqueueing

On singular pages where we might have comments, we’d like for WordPress to automatically load the JavaScript that’s responsible for the comment-reply behavior for threaded comments.

To do so, we adjust the previous function to include a call to enqueue the comment-reply JavaScript. Like so:

function butter_scripts_and_styles() {
  // previously enqueued and styles
  ...
  
  // enqueue the comment-reply JavaScript
  if ( is_singular() && comments_open() && get_option( 'thread_comments' ) ) {
    wp_enqueue_script( 'comment-reply' );
  }
  
}
add_action( 'wp_enqueue_scripts', 'butter_scripts_and_styles' );

Note that before we enqueue the script we’re first checking to see that we’re in a single page which allows comments and that those comments are threaded.

Style for I.E.

Lets say you want to enqueue a stylesheet that solves all the pesky problems that arise when viewing your site/theme on Internet Explorer versions older than IE9. How would you go about that? The first step is pretty much the same way as enqueueing the regular stylesheets. From within the function, enqueue the script.

function butter_scripts_and_styles() {
  // previously enqueued styles
  ...
  
  // enqueue the IE-specific stylesheet
  wp_enqueue_style( 'butter-for-ie', get_template_directory_uri() . '/css/styles-for-ie.css', array( 'butter-styles', 'typography' ), '1.0' );
  
  // previously enqueued scripts
  ...
}
add_action( 'wp_enqueue_scripts', 'butter_scripts_and_styles' );

Note that in the array of dependencies, we’re specifying that the IE stylesheet depends on our previously enqueued butter-styles, which is the main stylesheet (style.css) as well as the typography stylesheet. This makes sure that it loads after them.

Next, we need instruct WordPress to wrap this linked stylesheet in a conditional statement when its printed out in the head.

function butter_scripts_and_styles() {
  // previously enqueued styles
  ...
  
  // enqueue the IE-specific stylesheet
  wp_enqueue_style( 'butter-for-ie', get_template_directory_uri() . '/css/styles-for-ie.css', array( 'butter-styles', 'typography' ), '1.0' );
  wp_style_add_data( 'butter-for-ie', 'conditional', 'lt IE 9' );
  
  // previously enqueued scripts
  ...
}
add_action( 'wp_enqueue_scripts', 'butter_scripts_and_styles' );

wp_head and wp_footer

With that function in place, all you need to do now is make sure that you have <?php wp_head(); ?> in the header.php, right before end of </head> and also, to ensure that scripts that load in the footer load properly, also make sure to include <?php wp_footer(); ?> immediately before the </body> tag.

That’s it!