How To Properly Include CSS & Javascript In WordPress

One thing I see a lot in plugins and themes is incorrectly included scripts or CSS. The worst culprit is jQuery as if this is included twice it causes some frustrating javascript errors that are hard to spot. The usual problem is a plugin or theme including a google hosted jQuery and then another plugin which has correctly included it from the jQuery which comes with WordPress. This is the same for CSS, although it doesn’t cause massive errors that can cause your website not to function correctly, it can cause some very annoying styling issues.

First we will look at how to include CSS and then we will move onto Javascript and finally some tips on best practices when including either one.

How To Include CSS In WordPress

There is a few functions we will be looking at for including CSS correctly, wp_register_style(), wp_enqueue_style() and add_action(). With these three functions we can include styles into our page and make sure that they are including any other styles they depend on. WordPress has a great way of including styles, so it’s important we make the most of it.

Including Plugin CSS Styles

Including CSS files for a plugin is slightly different to including CSS from a theme. Here is a snippet of code to include these plugin styles in WordPress.

add_action( 'wp_enqueue_scripts', 'ew_register_plugin_styles' );
function ew_register_plugin_styles() {
	wp_register_style( 'ew-plugin-css', plugins_url( 'ew-plugin/css/ew-plugin.css' ) );
	wp_enqueue_style( 'ew-plugin-css' );
}

First of all we add an action for wp_enqueue_scripts, then we create a function for this action. Inside the function we use wp_register_style to setup our initial style, this creates the style ready to be included on the page, but it doesn’t include it yet. This is useful if you want to make your style conditional in a shortcode but you wish to register all your styles upfront. Next we enqueue the style using the name we gave to it earlier and voila! Our styles are included inside the head, exactly where they should be. Note: when we registered our CSS style we used plugins_url, this fetches the current directory where your plugins are stored /wp-content/plugins. The reason we use this function is that the WordPress installation could be inside a folder, this function will detect that for us.

Including Theme CSS Styles

This time we are going to include CSS styles for a theme, usually there is a style.css included directly into the theme, but sometimes you might want to include styles if there is an options page inside your theme (checkout my create easy options page article for more info on options pages). Let’s take a look at the code for this.

add_action( 'wp_enqueue_scripts', 'ew_register_theme_styles' );
function ew_register_theme_styles() {
	wp_register_style( 'ew-theme-css', get_template_directory_uri() . '/css/ew-theme.css' );
	wp_enqueue_style( 'ew-theme-css' );
}

It’s very similar to our previous code, except this time we concatenate the get_template_directory_uri() function with where our CSS style sits inside /wp-content/themes/your-theme/. This makes everything future proof, similar to the plugins url. It allows us to make sure we are in the right folder when including our styles. We also rename our styles to be called ew-theme-css so that it makes sense for other developers in the future and for ourselves when we wish to update our theme.

Extra Parameters wp_register_style

There is a few extra parameters we can provide wp_register_style than in the examples above. These make including CSS inside WordPress a lot easier, let’s take a look.

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

Above is all of the parameters you can provide the wp_register_styles function, so far we have only used $handle and $src. The $deps parameter allows you to specify other CSS files that the current stylesheet you are registering depends on. A perfect example is jQuery UI styles. You might want to include for example, core jQuery UI CSS whenever you are including jQuery UI tabs CSS, to keep the size of your page load down.

WordPress Enqueue CSS Dependants Parameter

add_action( 'wp_enqueue_scripts', 'ew_register_theme_styles' );
function ew_register_theme_styles() {
	wp_register_style( 'jquery-ui', get_template_directory_uri() . '/css/jquery/ui/jquery-ui.css' );
	wp_register_style( 'jquery-ui-tabs', get_template_directory_uri() . '/css/jquery/ui/jquery-ui-tabs.css', array('jquery-ui') );
	wp_enqueue_style( 'ew-theme-css' );
}

The files above register two styles, jquery-ui and jquery-ui-tabs. This allows us to set jquery-ui as a style that jquery-ui-tabs depends on. When we enqueue our style, WordPress also sees that we require another stylesheet and enqueues it for us before this style, awesome!

WordPress Enqueue CSS Version Parameter

The version parameter simply allows you to let browsers know the version of this CSS file has been updated, so that it loads a new version for users, rather than caching it. This attaches a query string to the end of the CSS file in the format of ?ver=1.0

add_action( 'wp_enqueue_scripts', 'ew_register_theme_styles' );
function ew_register_theme_styles() {
	wp_register_style( 'ew-theme-css', get_template_directory_uri() . '/css/ew-theme.css', array(), '1.0' );
	wp_enqueue_style( 'ew-theme-css' );
}

WordPress Enqueue CSS Media Parameter

The media parameter allows us to specify what type of media this stylesheet is aimed for. For example ‘screen’ or ‘print’, for a full list checkout this link on W3.org.

add_action( 'wp_enqueue_scripts', 'ew_register_theme_styles' );
function ew_register_theme_styles() {
	wp_register_style( 'ew-theme-css', get_template_directory_uri() . '/css/ew-theme.css', array(), false, 'screen' );
	wp_enqueue_style( 'ew-theme-css' );
}

The code above will output something similar to:

<link rel="stylesheet" type="text/css" href="http://www.website.com/wp-content/theme/my-theme/css/ew-theme.css" media="screen" />

How To Include Javascript In WordPress

Next we are looking at how to include Javascript files inside WordPress. This is exactly the same as including CSS styles, except it uses different functions. The functions we will be using this time are wp_register_script(), wp_enqueue_script() and add_action() again.

Including Plugin Javascript Files

This is very similar to including CSS plugin files, except we are using the new functions, take a look below and you will see how easy it is to include JS files.

add_action( 'wp_enqueue_scripts', 'ew_register_plugin_scripts' );
function ew_register_plugin_scripts() {
	wp_register_script( 'ew-plugin-js', plugins_url( 'ew-plugin/js/ew-plugin.js' ) );
	wp_enqueue_script( 'ew-plugin-js' );
}

You can see that we have included our Javascript files the same way as our CSS files, but this time we have used wp_register_script and wp_enqueue_script.

Including Theme Javascript Files

Again, this is very similar to our CSS example above.

add_action( 'wp_enqueue_scripts', 'ew_register_theme_scripts' );
function ew_register_theme_scripts() {
	wp_register_script( 'ew-theme-js', get_template_directory_uri() . '/js/ew-theme.js' );
	wp_enqueue_script( 'ew-theme-js' );
}

We register our script file, give our file a handle and then enqueue the script with that handle. It’s very easy once you have done it a couple of times. The parameters for including script files are the same as including CSS files, except for media. You can specify the dependants, the version and if you want the script to appear in the footer, checkout the next section for a bit about that.

Best Practices For Including Javascript In WordPress

One of the things I see far too much of is including Javascript files in the head of the document, WordPress used to make it a bit awkward to include your script files in the footer, but now they have added a parameter exactly for this purpose, so use it.

add_action( 'wp_enqueue_scripts', 'ew_register_theme_scripts' );
function ew_register_theme_scripts() {
	wp_register_script( 'ew-theme-js', get_template_directory_uri() . '/js/ew-theme.js', array(), false, true );
	wp_enqueue_script( 'ew-theme-js' );
}

For a full explanation on including jquery in the footer and how to get around a few issues with it, checkout my including jquery in the footer article.

One thing which you should really try and avoid is just hard coding script files, you can register scripts that are in a CDN by adding an absolute path to the functions above, so there isn’t really any need to hard code a javascript or CSS file.

Comments