Skip to content

Add docs for variations key in theme.json #49826

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
oandregal merged 3 commits into from
Apr 17, 2023
Merged

Add docs for variations key in theme.json #49826

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a24468b
Document variations in theme.json
oandregal Apr 14, 2023
9c4cffe
Fix grammar
andrewserong Apr 17, 2023
1f2098d
Add caveat about what style variations are considered
oandregal Apr 17, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions docs/how-to-guides/themes/theme-json.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ WordPress 5.8 comes with [a new mechanism](https://make.wordpress.org/core/2021/
- Top-level
- Block-level
- Elements
- Variations
- customTemplates
- templateParts
- patterns
Expand Down Expand Up @@ -1084,6 +1085,41 @@ Pseudo selectors `:hover`, `:focus`, `:visited`, `:active`, `:link`, `:any-link`
}
```

#### Variations

A block can have a "style variation", as defined per the [block.json specification](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/#styles-optional). Theme authors can define the style attributes for an existing style variation using the theme.json file. Styles for unregistered style variations will be ignored.

Note that variations are a "block concept", they only exist bound to blocks. The `theme.json` specification respects that distinction by only allowing `variations` at the block-level but not at the top-level. It's also worth highlighting that only variations defined in the `block.json` file of the block are considered "registered": so far, the style variations added via `register_block_style` or in the client are ignored, see [this issue](https://github.com/WordPress/gutenberg/issues/49602) for more information.

For example, this is how to provide styles for the existing `plain` variation for the `core/quote` block:

```json
{
"version": 2,
"styles":{
"blocks": {
"core/quote": {
"variations": {
"plain": {
"color": {
"background": "red"
}
}
}
}
}
}
}
```

The resulting CSS output is this:

```css
.wp-block-quote.is-style-plain {
background-color: red;
}
```

### customTemplates

<div class="callout callout-alert">Supported in WordPress from version 5.9.</div>
Expand Down