Intro to WordPress Plugin Development: Loading Scripts and Styles

We’ve done a lot to advance on the basics of WordPress plugin development during the Intro to WordPress Plugin Development series. Next, we’ll look at how to properly load scripts and styles.

The wrong way to load a script or style

It is possible to load a script or style into the site header using the wp_head action.

It would look like this.

function sd_load_script(){
    echo 'some jQuery code here';
}
add_action( 'wp_head', 'sd_load_script' );

The problem with that is if you load jQuery this way, and another plugin loads it the right way the site will end up with jQuery loading twice. It’s even possible that you are loading a different version of jQuery than the other plugin, which would create conflicts in the code.

Now that we know what the wrong way is, let’s look at the right way.

Why enqueue scripts in WordPress?

The enqueue script function in WordPress is designed so that all plugins, themes, and WordPress core works together nicely. The function will load the scripts and styles that plugins and themes ask it to, but it will make sure that each is only loaded once. Plus, WordPress comes with a number of built-in JavaScript libraries that can be used so plugin developers don’t have to go loading the libraries from third-party sources. This helps keep a site’s code slimmed down, which will reduce load times, and cause fewer code conflicts.

How to properly enqueue scripts and styles in WordPress

It’s actually pretty easy to load scripts and styles the right way in WordPress.

There are two components to loading a script or stylesheet in WordPress.

1. Registering the script
2. Enqueue the script

function sd_add_scripts(){
	wp_register_script( 'sd_my_cool_script', plugins_url( 'script.js', __FILE__ ), array( 'jquery' ), '1.0', true );
	wp_enqueue_script( 'sd_my_cool_script' );
 
	wp_enqueue_style( 'sd_my_styles', plugins_url( 'styles.css', __FILE__ ), '', '1.0' );
}
add_action( 'wp_enqueue_scripts', 'sd_add_scripts' );

There are five pieces to the wp_register_script function.

• Handle: This is the ‘sd_my_cool_script’ portion. This is the unique name of the script so that WordPress can identify it. This helps makes sure the script is only loaded once.
• Source: This is the location of the file we want to load. In this case, we’re using a file called script.js, which is located in the same folder as the file that is adding this function. The plugins_url function makes it easy for us to add this, without needing to know the exact URL of the file, since our plugin could be installed on many other sites.
• Dependencies: This specifies other JavaScript libraries that our script is dependent upon. In this case, ours is dependent on jQuery. This indicates to WordPress to load the jQuery library that is included with WordPress.
• Version: We can optionally provide a version number. The version number helps with caching the script file. If you ever update the plugin and change the contents of your script.js file, you can increment the version number (1.1, 2.0, or whatever) to force browsers to fetch a new version of the file. If you leave this off, a user’s browser could have the old version cached, and may not see the changes until they clear their cache.
• In Footer: This indicates whether or not our script is loaded in the footer. True = load in the footer. False = load in the header.

The wp_enqueue_script() function is what allows WordPress to process your script and output it where it is needed. We use this so that other plugins or the site owner can remove our script if they want to without having to touch our plugin’s code.

Styles

Stylesheets can easily be added using wp_enqueue_style. Settings for this function are similar to wp_register_script. We have a unique handle, the URL to the stylesheet, dependencies (in this case we have none), and the version of the stylesheet. We include the version for the same reason as before so that the user’s cache can be cleared if we update the stylesheet.

Conditionally loading styles and scripts

It’s a good practice to only load the styles and scripts in your plugin when they are needed. The reason why is we don’t want to slow down the site our plugin is installed on with unnecessary scripts or styles. It also reduces the likelihood that our plugins scripts and styles will conflict with another plugin or theme.

Conditionally load on admin only

To conditionally load the scripts and styles when on the admin pages only, we would use the following action:

add_action( 'admin_enqueue_scripts', 'our_function_name' );

Conditionally load on front end only

To conditionally load scripts and styles on the front end only (not on an admin page), we would use the following action:

add_action( 'wp_enqueue_scripts', 'our_function_name' );

Conditionally load on certain pages

We can also use PHP to add conditions to our functions to only load our scripts or styles on certain pages. Let’s say we only want a stylesheet to load on the homepage of our site.

function sd_homepage_style(){
	if( is_front_page() ) {
		wp_enqueue_style( 'sd_my_homepage_styles', plugins_url( 'styles.css', __FILE__ ), '', '1.0' );
	}
}
add_action( 'wp_enqueue_scripts', 'sd_homepage_style' );

With that function, the styles will only be applied to the homepage on the site. They won’t be used on any admin pages or any other front end page.