PHPackages                             humanmade/extended-block-variations - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. humanmade/extended-block-variations

ActiveWordpress-plugin[Utility & Helpers](/categories/utility)

humanmade/extended-block-variations
===================================

Extends theme.json block style variations to support external stylesheets via the non-standard 'stylesheet' property.

v1.1.0(1w ago)137↓50%[1 issues](https://github.com/humanmade/extended-block-variations/issues)GPL-3.0-or-laterPHPPHP >=8.2CI passing

Since Apr 21Pushed 1w agoCompare

[ Source](https://github.com/humanmade/extended-block-variations)[ Packagist](https://packagist.org/packages/humanmade/extended-block-variations)[ RSS](/packages/humanmade-extended-block-variations/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (2)DependenciesVersions (8)Used By (0)

Extended Block Variations
=========================

[](#extended-block-variations)

Extends WordPress theme.json block style variations with custom properties for external stylesheets.

Overview
--------

[](#overview)

WordPress supports defining block style variations in theme.json partials located in the `/styles/` directory. However, the native implementation doesn't support linking external CSS files to style variations, either by style\_handle or by file: reference.

This plugin adds support for this feature through a custom property in your theme.json variation files.

Usage
-----

[](#usage)

### Custom Property

[](#custom-property)

Add this custom property to your block style variation JSON files in `themes/your-theme/styles/.../*.json`:

#### `stylesheet` (string)

[](#stylesheet-string)

Path to an external stylesheet or a registered style handle.

- **File references**: Use `"file:./path/to/file.css"` to reference a CSS file relative to the JSON file's location
- **Style handles**: Use a string matching a registered WordPress style handle

### Example

[](#example)

**File**: `themes/your-theme/styles/blocks/button/primary.json`

```
{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "title": "Primary",
  "slug": "primary",
  "blockTypes": ["core/button"],
  "stylesheet": "file:./primary-button.css",
  "styles": {
    "color": {
      "background": "var:preset|color|primary",
      "text": "var:preset|color|white"
    }
  }
}
```

**File**: `themes/your-theme/styles/blocks/button/primary-button.css`

```
.is-style-primary {
  /* Additional styles requiring media queries or other CSS-only features */
  @media (max-width: 768px) {
    padding: 1em 2em;
  }
}
```

### File Path Resolution

[](#file-path-resolution)

File paths are resolved relative to the JSON file's directory:

- JSON at: `themes/your-theme/styles/blocks/button/primary.json`
- Reference: `"stylesheet": "file:./styles.css"`
- Resolves to: `themes/your-theme/styles/blocks/button/styles.css`

Use `../` to reference parent directories:

- Reference: `"stylesheet": "file:../../shared/button-base.css"`
- Resolves to: `themes/your-theme/styles/shared/button-base.css`

### Using Pre-registered Handles

[](#using-pre-registered-handles)

If you've already registered a style handle via `wp_register_style()`, reference it directly:

```
{
  "stylesheet": "my-custom-handle"
}
```

### Versioning stylesheets

[](#versioning-stylesheets)

WordPress normally sets block asset versions based on the version string in block.json. Since the schema for block style variation JSON partials does not include a version number, you can manually specify a version string in your stylesheet reference:

```
"stylesheet": "file:/variation-styles.css?ver=1.0.2"
```

If you omit the `ver` parameter, a version string will be computed by hashing the stylesheet. This requires an inefficient full-file read operation on every registration call, so this auto-versioning should only be used as a fallback convenience while actively developing styles.

How It Works
------------

[](#how-it-works)

1. WordPress core reads theme.json partials from `/styles/` and registers block style variations
2. This plugin scans the same directory for JSON files containing a `stylesheet` property
3. For `file:` references:
    - The path is resolved relative to the JSON file's location
    - A unique style handle is generated based on the file path
    - The stylesheet is registered with WordPress (including RTL support and path data for inlining)
4. Stylesheets are enqueued via `wp_enqueue_block_style()`:
    - If block assets load on-demand: Enqueued when blocks with the variation class render
    - Otherwise: Enqueued immediately
5. WordPress handles merging the styles with theme.json definitions and potential inlining

Compatibility
-------------

[](#compatibility)

- **WordPress**: 6.6+
- **PHP**: 8.0+

This plugin extends core WordPress functionality and follows the same file structure conventions as WordPress core's theme.json parser.

API Reference
-------------

[](#api-reference)

### `Extended_Block_Variations\register_variation_stylesheets(): void`

[](#extended_block_variationsregister_variation_stylesheets-void)

Enqueues stylesheets for block style variations that define a custom `stylesheet` property. Handles both immediate and on-demand loading based on theme configuration.

Performance Optimizations
-------------------------

[](#performance-optimizations)

The plugin integrates with WordPress's block asset loading strategies:

- **On-demand loading**: When enabled, stylesheets only load when blocks with the variation are actually rendered
- **Automatic inlining**: Small stylesheets (under 40KB by default) may be inlined automatically
- **RTL support**: Automatically detects and loads RTL versions of stylesheets when available
- **File versioning**: Uses file modification time for cache busting

Integration with Theme
----------------------

[](#integration-with-theme)

WordPress core automatically registers block style variations from theme.json partials in the `/styles/` directory. This plugin enhances that process by:

1. Detecting variations with custom `stylesheet` properties
2. Resolving and registering the referenced stylesheets
3. Enqueueing them alongside the core-registered block styles

The plugin hooks into `after_setup_theme`, running before block registration to ensure stylesheets are ready when blocks render. No additional configuration is required - simply add the `stylesheet` property to your variation JSON files.

Setting Default Block Styles
----------------------------

[](#setting-default-block-styles)

To configure default block styling, use theme.json to set styles at the block level rather than the variation level. This is the WordPress-native approach and ensures proper inheritance and overrides.

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance78

Regular maintenance activity

Popularity13

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 89.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~36 days

Total

2

Last Release

12d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/a498e093283b7b42aa63d5f75851cda7ec4c4e2137cb8482e02d3181b48eafa3?d=identicon)[kadamwhite](/maintainers/kadamwhite)

---

Top Contributors

[![kadamwhite](https://avatars.githubusercontent.com/u/442115?v=4)](https://github.com/kadamwhite "kadamwhite (25 commits)")[![joeleenk](https://avatars.githubusercontent.com/u/6807390?v=4)](https://github.com/joeleenk "joeleenk (3 commits)")

---

Tags

pluginwordpresstheme.jsonblock-variations

### Embed Badge

![Health badge](/badges/humanmade-extended-block-variations/health.svg)

```
[![Health](https://phpackages.com/badges/humanmade-extended-block-variations/health.svg)](https://phpackages.com/packages/humanmade-extended-block-variations)
```

###  Alternatives

[afragen/git-updater

A plugin to automatically update GitHub, Bitbucket, GitLab, or Gitea hosted plugins, themes, and language packs.

3.3k1.7k](/packages/afragen-git-updater)[webdevstudios/cmb2-attached-posts

Custom field for CMB2 for creating post relationships.

13465.7k](/packages/webdevstudios-cmb2-attached-posts)[iceicetimmy/acf-post-type-selector

Post type selector for Advanced Custom Fields.

559.0k](/packages/iceicetimmy-acf-post-type-selector)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)