Migrating to Newer Versions

This guide documents the changes between different theme.json versions and how to upgrade. Using older versions will continue to be supported. Upgrading is recommended because new development will continue in the newer versions.

Migrating from v1 to v2

Upgrading to v2 enables some new features and adjusts the naming of some old features to be more consistent with one another.

How to migrate from v1 to v2:

1. Update version to 2.
2. Rename the properties that were updated (see below) if you’re using them.

Refer to the dev note for the release and the reference documents for the respective v1 and v2 versions.

Renamed properties

New properties

New top-level properties: customTemplates, templateParts.

Additions to settings:

• settings.appearanceTools
• settings.border.color
• settings.border.style
• settings.border.width
• settings.color.background
• settings.color.defaultGradients
• settings.color.defaultPalette
• settings.color.text
• settings.spacing.blockGap
• settings.typography.fontFamilies
• settings.typography.fontStyle
• settings.typography.fontWeight
• settings.typography.letterSpacing
• settings.typography.textColumns
• settings.typography.textDecoration
• settings.typography.textTransform

Additions to styles:

• styles.border.color
• styles.border.style
• styles.border.width
• styles.filter.duotone
• styles.spacing.blockGap
• styles.typography.fontFamily
• styles.typography.fontStyle
• styles.typography.fontWeight
• styles.typography.letterSpacing
• styles.typography.textColumns
• styles.typography.textDecoration
• styles.typography.textTransform

Changes to property values

The default font sizes provided by core (settings.typography.fontSizes) have been updated. The Normal and Huge sizes (with normal and huge slugs) have been removed from the list, and Extra Large (x-large slug) has been added. When the UI controls show the default values provided by core, Normal and Huge will no longer be present. However, their CSS classes and CSS Custom Properties are still enqueued to make sure existing content that uses them still works as expected.