CSS Optimization Overview

This guide reflects the CSS features actually implemented in ZiziCache. CSS optimizations run inside the main HTML optimization pipeline and are controlled by configuration flags in SysConfig::$config.

CSS Minification

Minification is enabled by css_minify. ZiziCache scans linked stylesheets (), reads local files, and writes minified copies to the cache directory.

• Uses MatthiasMullieMinifyCSS for minification.
• Skips files larger than 2 MB and files that cannot be read.
• Rewrites relative URLs inside CSS to absolute paths.
• Injects font-display: swap into @font-face rules via Font::inject_display_swap().
• Writes cached files to wp-content/cache/zizi-cache/ with a hash-based filename and creates a .gz variant.

You can exclude files from minification with the zizi_cache_exclude_from_minify:css filter.

Used CSS / Remove Unused CSS (RUCSS)

When css_rucss or css_critical is enabled and the Sabberworm parser is available, ZiziCache uses the unified CSSEnhanced pipeline. It parses the HTML, collects selectors, and builds a per‑URL‑type „used CSS“ file.

• Cache path: wp-content/cache/zizi-cache/css/{url_type}.zc.css
• URL type examples: front, home, page-123, post, category, etc.
• Selectors are kept if they are present in the HTML or if they match an internal dynamic-selector allowlist (page builders, popups, sliders, etc.).
• Additional selectors can be forced via css_rucss_include_selectors.

Important: this is selector-based analysis, not a visual rendering engine. If styles are applied only after JavaScript runs, add the relevant selectors to the include list.

Stylesheet Exclusions

Built‑in exclusion patterns cover common theme/plugin CSS (Elementor, Bricks, WooCommerce, etc.). You can extend this list:

• css_rucss_exclude_stylesheets — do not process these files.
• css_critical_exclude_stylesheets — exclude from critical/used CSS.
• css_critical_exclude_google_fonts — skip Google Fonts in critical CSS.

Deferred CSS Loading Methods

When used CSS is injected, the original stylesheet can be deferred using css_rucss_method:

• async — uses media="print" + onload swap.
• domcontentloaded — moves the URL to data-dcl-href and applies zizi-dcl-css.
• interaction — moves the URL to data-href and applies zizi-deferred-css.
• delay — moves the URL to data-zizi-deferred.
• remove — removes the original stylesheet tag.

ZiziCache injects its core JS library automatically when deferred CSS attributes are present.

Used CSS Injection Method

Used CSS is injected inline by default. If css_critical_method is set to file, ZiziCache injects a preload + stylesheet pointing to the cached .zc.css file and appends a cache-busting ver parameter stored in zizi_cache_used_css_time.

Cache Invalidation

Used CSS is cached per URL type. If you change styles or exclusions, clear the Used/Critical CSS cache (it removes cached .zc.css files and resets timestamps).

Troubleshooting

• Missing styles: add selectors to css_rucss_include_selectors or exclude the stylesheet from processing.
• Builder or editor issues: verify page‑builder exclusions and test with optimization bypass on editor sessions.
• Changes not visible: clear Used CSS cache and page cache.