Critical CSS

Critical CSS reduces load time by generating two optimized CSS files: one for inline styling of content that appears in the initial viewport for a page, and another linked file for styling the rest of the page. Trellis creates these files for each page of your WordPress site.

How Is Critical CSS Generated?

1. When a page is first visited by a non-logged in user, your Trellis instance submits it to the Trellis Services API hosted by Mediavine. Access to this service is included in your license.
2. The page is rendered in a browser with a 1300 x 900 px viewport and its CSS stylesheet is audited.
3. Any CSS styles that affect content in this viewport are saved into a minified primary Critical CSS file.
4. Any CSS styles that fall outside of this viewport are saved into a minified secondary Non-Critical CSS file. CSS styles that are not referenced by elements on the page are completely left out.
5. When the Critical and Non-Critical files are complete, the Trellis Services API notifies your Trellis instance to download them. These files are saved into your WordPress installation (specifically the /wp-content/mvt-critical/ directory).
6. The next time the page is visited by a non-logged in user, the Critical and Non-Critical CSS files are served.

How To Determine the Critical CSS Status of a Page

When logged in to WordPress, a Critical CSS Status will appear in the admin bar when you view a page on your site (See Changes to WordPress for more information). The status tells you where Trellis is in the Critical CSS generation process:

When Does Critical CSS Get Refreshed?

Knowing that Critical CSS files are only generated when a non-logged in user views a page, it’s natural to wonder when Trellis will trigger an update to those files. Here are the events that prompt Critical CSS to purge its existing files:

If you’ve made a significant change to your theme’s design or functionality, you may want to tell Trellis to discard all existing Critical CSS files and rebuild them from scratch (also referred to as purging). For more information on when to use the Purge features, see Critical CSS in the Admin Bar in the Help Center.

Advanced Functionality

There are instances where you might want to alter Critical CSS functionality because you intend to use your child theme with other plugins. You might also use JavaScript to alter the styling of page elements after page load. In these scenarios, Critical CSS’ default functionality might give you unexpected results. For dynamically altered elements that appear in the initial viewport, you’ll want to consider adding their selectors to the Critical CSS file. If those elements appear outside of the initial viewport, add their selectors to the Non-Critical CSS file.

Adding CSS to the Critical CSS File

By default, if a CSS selector doesn’t match an element in the initial 1300 x 900 px viewport of a page, it gets saved to that page’s Non-Critical CSS file. This might not be the desired behavior. It’s possible that you need some styles to be present at page load to prevent a layout shift or stop a flash of unstyled content for elements close to the viewport, but not in it.

While publishers can add CSS selectors manually to the Force Critical CSS list in Trellis Settings, you can include them programmatically by adding code to your child theme’s functions.php file.

In the example below, selectors are added to an array. You can add full selector names or partial names if you want to match a range of selectors. An add_filter is then used to add the matching selectors to Trellis’ Force Critical CSS list. When a page gets submitted to the Trellis Services API, any matching CSS selectors are added to the Critical CSS file.

Example

In the example below, a site uses WP Recipe Maker and wants all styles included in the primary Critical CSS file. Since all WP Recipe Maker styles begin with the suffix “wprm,” Trellis will add all of the matching styles.

function theme_forced_styles( $selectors ) {
    $selectors[] = 'wprm';
    return $selectors;
}

add_filter( 'mv_trellis_css_force_keep', 'theme_forced_styles' );

You can add multiple styles to the array by using an array_merge():

array_merge( $selectors, [ 'wprm', 'blue' ] )

You can also add them individually by using multiple lines:

$selectors[] = 'wprm';
$selectors[] = 'blue';

Adding CSS to the Non-Critical CSS File

When creating the secondary Non-Critical CSS file, Trellis leaves out any CSS styles that don’t apply to elements on the page. This can create issues if elements are added to the page markup after the initial page load. The Trellis Services API does not execute JavaScript at runtime, so styles for these added elements would not be included in the Non-Critical CSS file.

Publishers can add these style selectors manually in Trellis Settings, but if you design your child theme to work with a third-party plugin (or are adding your own JavaScript that impacts content styling) you may want to include selectors programmatically. You do this by adding code to your child theme’s functions.php file.

Just like with Force Critical CSS, the example below shows a custom function where selectors are added to an array. You can add full selector names or partial names if you want to match a range of selectors. An add_filter is then used to add the matching selectors to Trellis’ Force Non-Critical CSS list. Any CSS styles that match the expression will get added to the Non-Critical CSS file.

Example

In the example below, dynamic page elements marked with “pop-up” are styled via JavaScript after page load. Specifying “pop-up” will add all matching styles.

function theme_allowlist_styles( $selectors ) {
    $selectors[] = 'pop-up';
    return $selectors;
}

add_filter( 'mv_trellis_css_allowlist', 'theme_allowlist_styles' );

You can add multiple styles to the array by using an array_merge():

array_merge( $selectors, [ 'pop-up', 'red' ] )

You can also add them individually by using multiple lines:

$selectors[] = 'pop-up';
$selectors[] = 'red';

Issues with Critical CSS

If you encounter problems using Critical CSS during development, refer to Troubleshooting.