enqueue-thumbnail

How to enqueue Scripts & Stylesheets to WordPress via a plugin

Like many front-end developers, I used to add  Scripts and Stylesheets to my themes in a very crude way. Pasting them directly onto the header.php theme file. Yes this can work, but it’s not best practice and can have the following side effects:

  1. Scripts being run more than once.
    Most WordPress sites use plugins. Most plugins use jQuery, so chances are you’ll have the script running twice if you hard-code it in.
  2. File magnification doesn’t work.
    If you’re looking to compress your files via a plugin like WP Minify, then you can’t because they’re hard-coded.
  3. Running files unnecessarily
    Hard coding scripts in the header mean they’ll run on every page unless you wrap them in conditional statements. Files don’t always need to run on every page.

Enter the wp_enqueue_script & wp_enqueue_style functions

These two very helpful WordPress functions are here to help us do it properly. Rather than hard-coding Scripts and Stylesheets, we can enqueue them into wp_head function via our theme’s functions file.

To demonstrate WP Enqueue in the video above, I installed BX Slider. BX Slider is a great example for demonstrating WP enqueue because it requires a variety of files including jQuery, it’s own JavaScript files and a Stylesheet.

Enqueueing via the functions.php file

Although we recommend enqueuing via creating a plugin, you can still add the commands to your theme’s functions.php file that’s located on the root level of your theme. Here’s the initial code from the video, along with my annotations to explain what’s happening.

function james_adds_to_the_head() { // Our own unique function called james_adds_to_the_head
	wp_enqueue_script('jquery');  // Enqueue jQuery that's already built into WordPress
	wp_register_script( 'add-bx-js', get_template_directory_uri() . '/jquery.bxslider/jquery.bxslider.min.js', array('jquery'),'',true  ); // Register our first script for BX Slider, to be brought out in the footer
	wp_register_script( 'add-bx-custom-js', get_template_directory_uri() . '/jquery.bxslider/custom.js', '', null,''  ); // Register our second custom script for BX
	wp_register_style( 'add-bx-css', get_template_directory_uri() . '/jquery.bxslider/jquery.bxslider.css','','', 'screen' ); // Register the BX Stylsheet
	wp_enqueue_script( 'add-bx-js' );  // Enqueue our first script
	wp_enqueue_script( 'add-bx-custom-js' ); // Enqueue our second script
	wp_enqueue_style( 'add-bx-css' ); // Enqueue our stylesheet
}
add_action( 'wp_enqueue_scripts', 'james_adds_to_the_head' ); //Hooks our custom function into WP's wp_enqueue_scripts function

Enqueueing via a plugin

For that extra level of safety and control, we recommend enqueuing via a separate  dedicated plugin. In the video, I demonstrate how simple this is. Firstly, create a folder within WordPress’ plugin folder located at /wp-content/plugins/. Name your folder something useful like ‘theme-scripts’ and create a php file with the exact same name within (i.e theme-scripts.php). Then, simply add and customise the following code, as per our example.

<?php
/*
Plugin Name: James' WP Enqueue Scripts &amp; Styles
Plugin URI: http://www.creare.co.uk/
Description: This is my own custom plugin for enqueuing Scripts and Styles in my WordPress theme
Version: 1.0
Author: James Bavington
Author URI: http://twitter.com/jamesbavington
License: Help yourselves to the shelves
*/

function james_adds_to_the_head() {

	//wp_enqueue_script('jquery');

	wp_register_script( 'add-bx-js', get_template_directory_uri() . '/jquery.bxslider/jquery.bxslider.min.js', array('jquery'),'',true  );
	wp_register_script( 'add-bx-custom-js', get_template_directory_uri() . '/jquery.bxslider/custom.js', '', null,''  );
	wp_register_style( 'add-bx-css', get_template_directory_uri() . '/jquery.bxslider/jquery.bxslider.css','','', 'screen' );

	wp_enqueue_script( 'add-bx-js' );
	wp_enqueue_script( 'add-bx-custom-js' );
	wp_enqueue_style( 'add-bx-css' );

}

add_action( 'wp_enqueue_scripts', 'james_adds_to_the_head' );

Don’t forget to delete any registering or enqueueing that you don’t need, because in our example we’re registering and enqueueing two JavaScripts and a Stylesheet.

Introducing WP Headmaster

Since writing this post, I have also authored my first public plugin for WordPress called WP Headmaster. WP Headmaster provides a simple way to enqueue and add common items into the head tag of your WordPress theme. Designed to work alongside Yoast’s WordPress SEO plugin, WP Headmaster adds features such as Google Analytics, jQuery, icons and much more. Please check it out on the WordPress Plugin Directory.

  • http://www.shovan.co.uk/ Shovan

    Nice one thanks

  • OOTH

    Excellent tutorial, thanks. I’ve now created my first simple plugin which loads a stylesheet – yay! One question. If my loaded stylesheet modifies a style already specified, then it seems that the theme takes precedence. How do I force my stylesheet to take precedence?

    I’m assuming it’s to do with the order in which the styles are loaded, but the codex isn’t clear about whether styles in a dependent stylesheet (i.e. loaded first) are overwritten by my styles. Even then, I’m struggling to work out the handle of the default theme’s stylesheet.

    Let’s take the 2012 theme for example, whose stylesheet is style.css, containing

    .main-navigation li a:hover {
    color: #000;
    }

    and I want to override this in my stylesheet with

    .main-navigation li a:hover {
    color: #fff;
    }
    My stylesheet is being enqueued, because other styles are showing, but the hover text colour is still black. What am I missing?

    • http://www.creare.co.uk/ James Bavington

      OOTH, thank’s for taking the time to read my post, and great to hear your plugin is working. Couple of ways of doing this. Essentially, if your two different styles on each stylesheet have the same authority, it’s the last one loaded that will take precedence. You can change the priority of where your plugins stylesheet is loaded by appending the add_action() function. If you add a third parameter like this:

      add_action( 'wp_enqueue_scripts', 'james_adds_to_the_head', '999' );

      It will enqueue your stylesheet as far down as possible within wp_head(). Alternatively, you can give your CSS code prominence by adding the !important declaration. Add !important to your CSS that you wish to be used like this:


      .main-navigation li a:hover {
      color: #fff !important;
      }

      Hope that helps.

      • OOTH

        Easy when you know how, eh? I went with the add_action option, as there are likely to be a few instances and it doesn’t seem sensible to scatter !important throughout a style sheet. Works like a dream. Thanks!

        • http://www.creare.co.uk/ James Bavington

          Cool, glad that works!

  • http://www.creare.co.uk/ James Bavington

    Hi Yessie, how have you added it already, that causes the site to break? Is the page online so that I can take a look for you?

  • Manuel Aullo

    Plugin is nicely working. Thank you both. Cheers

    • http://www.creare.co.uk/ James Bavington

      Thank you Manuel – great to hear that’s worked for you!

  • http://www.westerdale.biz/ Daniel Westerdale

    Hi really good post . If I wanted to enqueue your css file in your PLUGIN_DIR/CSS then would it not be better to use Global var that points to this CSS dir rather than the css in the current theme dir as you have. For my sins I am doing a bit of housekeeping on my blog so having code a bit of PHP ;-(

  • Nigel Stratton

    Point 2. should be File Minification, not File Magnification. :)

  • http://dailyprofit24.xyz/ himel22

    i couldn’t fix my theme styles via calling wp_enqueue.. but i can only call wp_enqueue_style( ‘main_css’, get_stylesheet_uri() ); it’s working…but other styles not working… anyone can help ?

  • Peter James

    Thanks for the tutorial! I’m trying to follow your method but as soon as I add the add_action line I get a 500 error. Any advice? Here is my code…