How to add Stylesheets and Scripts in WordPress?

August 4, 2014

 - Tags: ,

Overview

In a typical website, to add stylesheets and scripts you just need to respectively include a <link> and <script> tag in the <head> section of your html document. Unfortunately, in WordPress websites you can’t do this directly. In this article, I will show you what is the proper way to include stylesheets and scripts in WordPress.

Let’s say you want to include a css stylesheet in your html document. Your first guess might be to open the header.php file and to include a <link> tag pointing to your css stylesheet, before wp_head(). This is a good guess, however, this is not the WordPress way. WordPress actually offers some functions to enqueue stylesheets automatically. This means that we will use a WordPress function to create the relevant <link> and <script> tags in the <head> section of the html document.

Add a stylesheet

Suppose you want to add a css stylesheet called style.css, located at the root of your theme directory:

  1. First, open the functions.php file of your theme
  2. Then, create a wrapper function enqueue_my_styles() containing the wp_enqueue_style() function:
     
    		function enqueue_my_styles() {
    			wp_enqueue_style( 'style', get_template_directory_uri() . 'style.css' );
    		}
    	
    • The first argument of our function (i.e ‘style’) is arbitrary. It is meant to identify the stylesheet you are enqueuing. If you want to enqueue another stylesheet, you will need to choose a different name for the first argument.
    • The second argument is the path to your css stylesheet. Please note that for this snippet to work you need to put yourstyle.css file at the root of your theme directory. If you want to put your style.css file at another location, you will also need to modify the above snippet accordingly.
  3. Finally, you need to hook the above snippet to the wp_enqueue_scripts action hook:
     
    	function enqueue_my_styles() {
    		wp_enqueue_style( 'style', get_template_directory_uri() . 'style.css' );
    	}
    	add_action( 'wp_enqueue_scripts', 'enqueue_my_styles' );
    	

    The last line of this snippet will call enqueue_my_styles() at the right moment during the loading process of WordPress. As a word of caution, please note that although we enqueue stylesheets, we are still using the wp_enqueue_scripts action hook. The name chosen by WordPress can lead to confusion, but there is no mistake, it is the right way to do it.

That’s it. If you load your page now, you will notice that WordPress has added a <link> tag in the <head> section of your html document:

<link rel='stylesheet' id='style-css'  href='http://mywebsite.com/wp-content/themes/mytheme/style.css?ver=4.0' type='text/css' media='all' />

The id attribute is the first argument passed to wp_enqueue_style(), to which ‘-css’ was appended. The href attribute is the second argument passed to wp_enqueue_style().

Add a script

Now, we also want to add a javascript file called myscript.js, located in the /js folder, relative to the directory of our theme. The procedure to follow is exactly the same as for adding stylesheets, except that this time we will use wp_enqueue_script() instead of wp_enqueue_style():

 
	function enqueue_my_scripts() {
		wp_enqueue_script( 'script', get_template_directory_uri() . 'js/myscript.js' );
	}
	add_action( 'wp_enqueue_scripts', 'enqueue_my_scripts' );

Now, if you load the page you will find that WordPress has added this line in the <head> section of your html document:

	<script type='text/javascript' src='http://mywebsite.com/wp-content/themes/mytheme/js/myscript.js?ver=4.0'></script>

Advanced tips

Both wp_enqueue_style() and wp_enqueue_script() actually offers a couple of advanced parameters to play with our stylesheets and scripts:

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

So far, we have just seen $handle and $src. Let’s see the others and how they can be helpful.

#1: Manage Dependency

In both wp_enqueue_style() and wp_enqueue_script(), the $deps parameter allows us to manage dependency by specifying them in an array. For example, if our script depends on the jQuery library, we can write our wp_enqueue_script() function this way:

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

WordPress will make sure that myscript.js will only be loaded after jQuery. For this snippet to work, we need jQuery to have been enqueued or registered before (I explain the difference between these two concepts here).

In the particular case of jquery, WordPress registers it by default, so no need to do it by yourself, unless you want a specific version. As a side note, for a complete list of the scripts registered by WordPress by default, you can follow this link.

#2: Remove version number

You may have noticed that by default WordPress includes a version number at the end of the styles and scripts it loads (?ver=4.0):

	<link rel='stylesheet' id='style-css' href='http://mywebsite.com/wp-content/themes/mytheme/style.css?ver=4.0' type='text/css' media='all' />
	<script type='text/javascript' src='http://mywebsite.com/wp-content/themes/mytheme/js/myscript.js?ver=4.0'></script>

In wp_enqueue_script() and wp_enqueue_style(), the fourth argument $ver specifies the version number of the script/style, and is optional. Since we did not specify it, by default WordPress put the WordPress version number (4.0 in our case).

This may sound like not very important at first, but actually these type of query strings do not work well with some cache mechanisms: in some cases, caches systematically ignore caching parameters whenever they see query strings at the end of resource names.

This is why I recommend to get rid of these query string by specifying null for the $ver argument:

	wp_enqueue_script( 'style', 'http://mywebsite.com/wp-content/themes/mytheme/js/myscript.js', array(), null);

Now, when we load our page, there isn’t any query string appended to the script name anymore.

	<script type='text/javascript' src='http://mywebsite.com/wp-content/themes/mytheme/js/myscript.js'></script>

This will help our script to be better cached and our website to be faster.

#3: Load scripts at page bottom

You have certainly heard the tip advocating to load javascript files at the bottom of the page, just before the </body> tag. This allows for faster page loading and better user experience.

By default, WordPress loads the scripts in the <head> section of the html document. However, wp_enqueue_script() have an option to change that:

 
wp_enqueue_script( 'style', get_template_directory_uri() . 'js/myscript.js', array(), null, true );

The last argument set to true tells WordPress to load the script at the bottom of the page, instead of in the <head> section. If you look at the html code of your page, you should now see this:

 
<script type='text/javascript' src='http://mywebsite.com/wp-content/themes/mytheme/js/myscript.js'></script>
</body>

#4: Specify the media attribute for css stylesheets

By default, WordPress specifies all for the media attribute of your stylesheet:

	<link rel='stylesheet' id='style-css' href='http://mywebsite.com/wp-content/themes/mytheme/style.css' type='text/css' media='all' />

We can change this by specifying the $media argument of the wp_enqueue_style() function:

 
	wp_enqueue_style( 'style', 'http://mywebsite.com/wp-content/themes/mytheme/js/myscript.js', array(), null, 'screen');

Now your stylesheet is declared with the right media attribute in the html document:

	<link rel='stylesheet' id='style-css' href='http://mywebsite.com/wp-content/themes/mytheme/style.css' type='text/css' media='screen' />

Conclusion

WordPress provides 2 functions to add stylesheets and scripts in your page, respectively called wp_enqueue_style() and wp_enqueue_script().

To add a stylesheet or a script on your page, you need to use these functions in the functions.php file of your theme. After you passed the name and path of the resources to be included as arguments to these functions, you need to hook them to the action hook wp_add_scripts.

Besides the resource name and path, it is also possible to pass other arguments to wp_enqueue_style() and wp_enqueue_script() to better control how stylesheets and scripts are added to your page

If you liked the article, you can subscribe to my blog to receive updates when new articles are posted.

If you would like to know more about WordPress Excerpts & “Read More” tags, please check out the below resources.

Additional Resources

  • Another Tutorial on wpbeginner.com: Link
  • Official documentation for the wp_enqueue_style() function: Link
  • Official documentation for the wp_enqueue_script() function: Link
  • Official documentation for the wp_enqueue_scripts action tag: Link

Comments (2)

    1. Thanks for your message 🙂
      I just checked out your article to conditionally enqueue scripts/css based on custom fields, looks good!
      I think this principle can be used to customize a lot of behaviour in wordpress. It is quick and dirty but works great!
      I use this idea to attach a SEO h1 tag on top of articles/pages on my ecommerce websites (the higher in the html, the more important it is for google)

      Julien Klepatch

Leave a Reply