Ollie Theme Academy

Understanding Settings

Should I use version 3 of theme.json?

For new projects, always use the latest theme.json version (currently version 3 as of WordPress 6.6). You get access to the newest features and follow current best practices for block theme development.

For existing themes, be more cautious. If you don’t control the WordPress version (like with distributed themes), updating could break compatibility. Version 2 themes work perfectly fine on modern WordPress.

Consider the maintenance overhead – updating theme.json versions means updating everywhere it’s used: parent themes, child themes, and any PHP filters. Unless there’s a compelling new feature you need, the effort may not be worth it.

The golden rule: don’t change something that’s working without a good reason. Version 2 themes are stable and functional, so focus your energy on features and user experience rather than version bumps.

Back to: Ollie Theme Academy > Understanding Settings