Register & Enqueue Style Generator
Generate wp_enqueue_style() code with dependencies, a cache-busting version, a media query and conditional loading.
<?php
/**
* Enqueues the "my-plugin-frontend-style" stylesheet.
*/
function my_plugin_enqueue_styles() {
$src = plugins_url( 'assets/css/frontend.css', __FILE__ );
$file = plugin_dir_path( __FILE__ ) . 'assets/css/frontend.css';
// filemtime changes whenever the file does, so browsers never serve a stale copy.
$version = file_exists( $file ) ? filemtime( $file ) : false;
wp_enqueue_style(
'my-plugin-frontend-style',
$src,
array(),
$version,
'all'
);
}
add_action( 'wp_enqueue_scripts', 'my_plugin_enqueue_styles' );
Output is valid and updates as you type.
Fix the highlighted fields to update the output.
Point at the stylesheet, say where it loads and what it must come after, and the generator writes the wp_enqueue_style() call with a cache-busting version and the right hook.
How to use
- Name the handle and prefix it. Other code uses it to depend on your stylesheet or to dequeue it.
- Give the path relative to your plugin or theme root. The generator builds both the URL and the filesystem path, since the version needs the file itself.
- List dependencies by handle. A stylesheet loads after everything it depends on, which is how you win the cascade without
!important. - Leave the version on filemtime so a changed file is never served from cache.
- Set the media value if the rules are for print or a narrow screen, and pick a conditional if the file only matters on some pages.
Example
A print stylesheet in a parent theme that must come after the main stylesheet, versioned from a constant:
wp_enqueue_style(
'acme-print',
$src,
array_map( 'trim', explode( ',', 'acme-frontend-style' ) ),
$version,
'print'
);Front-end stylesheets hook wp_enqueue_scripts, the same hook scripts use. There is no separate styles hook, which surprises people reading the function names.
Pitfalls
- Front-end styles belong on
wp_enqueue_scripts. There is nowp_enqueue_styleshook, and code attached to that name never runs. - A media value of print still downloads the file. It only stops the rules applying, so it is not a performance win.
- Dependencies decide order, and order decides the cascade. Two stylesheets with equal specificity are settled by which one loaded second.
filemtime()warns on a missing file, which is why the generated code checksfile_exists()first.- Enqueueing a child theme path with
get_template_directory_uri()points at the parent. Child theme files needget_stylesheet_directory_uri(), which is what the child theme option writes. - An unprefixed handle can collide with another plugin’s, and the first registration wins silently.
- Editor styles are a separate mechanism:
add_editor_style()orenqueue_block_editor_assets, not this hook. - Loading one stylesheet per feature costs a request each. Combine them unless HTTP/2 and a small file make it moot.
Compatibility
wp_enqueue_style() has taken these five arguments since WordPress 2.6, and nothing here needs a newer release. The generated code targets PHP 7.0 and later, and the tool runs entirely in your browser.
Frequently asked questions
Why is my stylesheet loading before the theme’s?
Does a print stylesheet slow the page down?
Child theme or parent theme path?
get_template_directory_uri() always points at the parent, which is the usual reason a child theme file 404s.How do I style the block editor?
add_editor_style() for the classic editor and enqueue_block_editor_assets for blocks. This hook only affects the rendered page.