What is appearanceTools in theme.json?

26 June 2023 James Koussertari

appearanceTools themejson

The appearanceTools setting in theme.json enables a number of settings in the editor that are disabled by default. It takes a boolean value and it’s false by default.

To enable appearanceTools, simple add this to your theme.json:

  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 2,
  "settings": {
    "appearanceTools": true

In v2 of theme.json, setting appearanceTools to true, enables the following settings, that are disabled by default:

Should I enable appearanceTools in theme.json?

The reason this setting exists is to make it simple to opt-in to new design tools as they are added in the future, rather than having to opt-in to each one individually. This is helpful since new features get added frequently.

Also, this setting reduces the size of the theme.json file, which is a small bonus, but every line counts, right!

For these reasons, we suggest enabling it, especially if you are just starting out building Block Themes, as it will save you some time trying to figure out how to turn on specific settings individually.

Do I need all the UI controls that appearanceTools enables?

If you don’t need all of the settings you can simply ignore them in the editor and it will not cause you any issues, other than perhaps a few more settings available than you need.

Eventually once you’re more adept with theme.json, you could set appearanceTools to false and be more selective about which settings are available per block. Just bear in mind that any new settings added to Gutenberg will need to be enabled manually in theme.json.

Now you know what appearanceTools does and its benefits, it’s up to you whether you enable or disable it. There is no right or wrong and it’s completely personal preference.

26 June 2023 James Koussertari