Registering custom aspect ratios in WordPress 6.6

With all the major theming features that landed in WordPress 6.6, it’s easy to overlook some of the smaller quality-of-life enhancements. One of those is custom aspect ratio support via theme.json.

Before 6.6, you had to rely on the WordPress-defined aspect ratios or work around those design limitations with custom image sizes (which is more appropriately used for defining image resolutions).

Now you can register any aspect ratio you need—and as many as you like, within reason. Follow along to learn how to add them.

Digging into aspect ratios

So what is an aspect ratio exactly? It’s the ratio between the width and height of an image or whatever element it is applied to. For example, 1:1 is square, and 3:4 is a modern portrait ratio. Disciplines from fine art to commercial photography have each settled on a number of industry-standard aspect ratios, and WordPress covers many of the most useful ones for web design and publishing by default.

Take a look at the default theme.json definition for aspect ratios:

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"settings": {
		"dimensions": {
			"aspectRatio": true,
			"aspectRatios": [
				{
					"name": "Square - 1:1",
					"slug": "square",
					"ratio": "1"
				},
				{
					"name": "Standard - 4:3",
					"slug": "4-3",
					"ratio": "4/3"
				},
				{
					"name": "Portrait - 3:4",
					"slug": "3-4",
					"ratio": "3/4"
				},
				{
					"name": "Classic - 3:2",
					"slug": "3-2",
					"ratio": "3/2"
				},
				{
					"name": "Classic Portrait - 2:3",
					"slug": "2-3",
					"ratio": "2/3"
				},
				{
					"name": "Wide - 16:9",
					"slug": "16-9",
					"ratio": "16/9"
				},
				{
					"name": "Tall - 9:16",
					"slug": "9-16",
					"ratio": "9/16"
				}
			]
			"defaultAspectRatios": true
		}
	}
}

In the code above, aspect ratios are controlled by three properties under settings.dimensions:

• aspectRatio: This Boolean value shows the controls for aspect ratios in the UI and defaults to true.
• aspectRatios: This array of objects defines aspect-ratio presets:
  • name: A translatable label for the aspect ratio in the UI.
  • slug: This unique key defines the preset and can contain alphanumeric characters, hyphens, or underscores (e.g., 3-4).
  • ratio: The CSS value for the aspect ratio (e.g., 3/4).
• defaultAspectRatios: This Boolean value enables or disables the Core-defined aspect ratios and defaults to true.

Defining custom aspect ratio presets via settings.dimensions.aspectRatios will add them to the UI dropdown for users and make them usable in your theme’s patterns and templates.

Registering custom aspect ratios

What if your latest theme showcased two new aspect ratios: 2:1 (Extra Wide) and 21:9 (Cinema)? In 6.6, now you can define these in theme.json.

Here’s what the 2:1 aspect ratio looks like when you apply it to the Post Featured Image block:

WordPress 6.6 does have some limitations. For now, you can only set aspect ratios for three blocks:

• Image
• Post Featured Image
• Cover

Let’s try adding the 2:1 and 21:9 aspect ratios. Add this code to your theme.json file:

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"settings": {
		"dimensions": {
			"aspectRatios": [
				{
					"name": "Extra Wide - 2:1",
					"slug": "2-1",
					"ratio": "2/1"
				},
				{
					"name": "Cinema - 21:9",
					"slug": "21-9",
					"ratio": "21/9"
				}
			]
		}
	}
}

Disabling the default aspect ratios

Sometimes, you might want to limit users to only your custom aspect ratios. Good news! It’s fast and easy to disable the Core presets. Merely set settings.dimensions.defaultAspectRatios to false.

Building off the above example, see what happens when you add this to your theme.json file:

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"settings": {
		"dimensions": {
			"aspectRatios": [
				{
					"name": "Extra Wide - 2:1",
					"slug": "2-1",
					"ratio": "2/1"
				},
				{
					"name": "Cinema - 21:9",
					"slug": "21-9",
					"ratio": "21/9"
				}
			],
			"defaultAspectRatios": false
		}
	}
}

From there, you should see only your custom aspect ratio presets in the UI.

Just a few last things

This may be one of the shortest tutorials I’ve ever written. This fairly straightforward feature didn’t take much to explain—but gives you so much design control that didn’t exist before. A small enhancement? Maybe. But I know I’ve needed it myself for a long time.

Props to @marybaum and @welcher for feedback and review on this post.