manifest / performance / miccss

MICCSS - Manual Inline Critical CSS

A WordPress plugin for manually inlining Critical CSS to improve page load performance. Defers non-critical CSS using preload with fallback.

by Thomas Kamau · github.com/tombrian/miccss · website

★ 1stars

0forks

Install

No release zip yet. The repository archive installs, but the folder name will carry the branch suffix and updates will not flow:

wp plugin install https://github.com/tombrian/miccss/archive/refs/heads/main.zip

Readme github.com/tombrian/miccss ↗

A WordPress plugin for manually inlining Critical CSS to improve page load performance. Defers non-critical CSS using preload with fallback.

Author: Thomas Kamau
Version: 1.0.0
Requires: WordPress 5.0+, PHP 7.4+

Features

🚀 Critical CSS Inlining: Manually inline critical CSS in the document head
⚡ Universal Async CSS: ALL non-critical CSS loads asynchronously automatically
🎯 Smart Skip Handles: Critical styles (admin-bar, dashicons) load synchronously
🔧 Enhanced Admin Interface: Easy-to-use configuration with live validation
📱 Universal Compatibility: Works with all themes, plugins, and devices
🔍 SEO Optimized: Dramatically improves Core Web Vitals and page speed scores
🛡️ Bulletproof Fallbacks: Comprehensive noscript support for all browsers
🧠 Memory Safe: Prevents JavaScript memory leaks with proper cleanup
🎛️ Granular Control: Fine-tune which styles load sync vs async

Installation

Download the plugin files
Upload the miccss folder to your /wp-content/plugins/ directory
Activate the plugin through the 'Plugins' menu in WordPress
Go to Settings > MICCSS to configure the plugin

How It Works

The plugin implements an enhanced two-step CSS optimization strategy:

Critical CSS: Inlined in the <head> section for immediate rendering of above-the-fold content
ALL Non-Critical CSS: Automatically loaded asynchronously using advanced preload method with comprehensive fallbacks

Enhanced Async CSS Loading Method

/**
 * Make ALL non-critical styles load asynchronously using "preload + onload"
 * and provide a <noscript> fallback.
 */
add_filter('style_loader_tag', function ($html, $handle, $href, $media) {
    // Don't touch admin, login, or the critical (above-the-fold) handles.
    if (is_admin() || is_login()) {
        return $html;
    }

    // Skip critical handles that should load synchronously
    $skip_handles = ['critical-css-handle', 'dashicons', 'admin-bar'];

    if (in_array($handle, $skip_handles, true)) {
        return $html;
    }

    // Default media
    $media = $media ?: 'all';

    // Build async tag: preload first, then switch to stylesheet on load
    $async  = "<link rel='preload' as='style' href='" . esc_url($href) . "' media='{$media}' ";
    $async .= "onload=\"this.onload=null;this.rel='stylesheet'\">";
    // Fallback for users with JS disabled and for older browsers
    $async .= "<noscript><link rel='stylesheet' href='" . esc_url($href) . "' media='{$media}'></noscript>";

    return $async;
}, 10, 4);

🆕 Key Improvements:

Universal Coverage: Affects ALL CSS files automatically (not just specific handles)
Smart Skipping: Preserves critical styles (admin-bar, dashicons, custom critical handles)
Enhanced Fallback: Robust noscript support for JavaScript-disabled browsers
Better Performance: Uses 4-parameter filter for more precise control
Memory Safety: Prevents JavaScript memory leaks with this.onload=null

Configuration

Admin Settings

Navigate to Settings > MICCSS in your WordPress admin to configure:

Enable MICCSS: Toggle the plugin on/off
Critical CSS: Paste your critical CSS code with live validation
Skip Handles (Critical Styles): Style handles that should load synchronously
Additional Skip Handles: Optional extra handles to preserve immediate loading
Minify Critical CSS: Automatically compress inline CSS
Cache Critical CSS: Cache processed CSS for better performance

🆕 Enhanced Functionality:

Automatic Detection: All CSS files are processed automatically
Universal Coverage: No need to specify individual handles to defer
Smart Defaults: Critical WordPress styles are preserved automatically

Generating Critical CSS

To generate critical CSS for your site, use these recommended tools:

Steps to Generate Critical CSS:

Visit one of the tools above
Enter your website URL
Copy the generated critical CSS
Paste it into the MICCSS settings page
Save and test your site

Usage Examples

Basic Usage

Install and activate the plugin
Generate critical CSS for your homepage
Paste the CSS in Settings > MICCSS
Enable the plugin and save

Advanced Usage

Exclude Specific Stylesheets

// In your theme's functions.php
add_filter('miccss_exclude_handles', function($handles) {
    $handles[] = 'custom-critical-style';
    return $handles;
});

Manually Add Critical CSS

// In your theme files
if (function_exists('miccss_add_critical_css')) {
    miccss_add_critical_css('
        body { margin: 0; }
        .header { background: #333; }
    ');
}

Check if MICCSS is Active

if (function_exists('miccss_is_enabled') && miccss_is_enabled()) {
    // MICCSS is active
    echo 'Critical CSS optimization is enabled';
}

Best Practices

Test Critical CSS: Always test your critical CSS on different devices and page types
Keep It Small: Critical CSS should be under 14KB for optimal performance
Above-the-Fold Only: Include only styles for content visible without scrolling
Regular Updates: Update critical CSS when making design changes
Monitor Performance: Use tools like PageSpeed Insights to measure improvements

Performance Benefits

Faster First Contentful Paint (FCP)
Improved Largest Contentful Paint (LCP)
Better Core Web Vitals scores
Reduced render-blocking resources
Enhanced user experience

Browser Support

Chrome 50+
Firefox 85+
Safari 10+
Edge 79+
Internet Explorer 11 (with fallback)

Troubleshooting

Critical CSS Not Showing

Check if the plugin is enabled in Settings > MICCSS
Verify critical CSS is properly pasted (no syntax errors)
Clear any caching plugins
Check browser developer tools for errors

Styles Not Loading

Verify exclude handles are correct
Check for JavaScript errors in console
Ensure noscript fallback is present
Test with caching disabled

Performance Issues

Reduce critical CSS size (aim for under 14KB)
Minimize critical CSS code
Remove unused critical CSS rules
Test on different devices

Hooks and Filters

Actions

miccss_before_critical_css - Fires before critical CSS output
miccss_after_critical_css - Fires after critical CSS output

Filters

miccss_critical_css - Filter critical CSS content
miccss_exclude_handles - Filter excluded style handles
miccss_defer_handles - Filter deferred style handles

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Changelog

1.0.0

Initial release
Critical CSS inlining
Non-critical CSS deferring
Admin interface
Noscript fallback support

License

This plugin is licensed under the GPL v2 or later.

Support

For support and questions, please create an issue on the plugin repository or contact Thomas Kamau.

Made with ❤️ by Thomas Kamau