Developer · Guide
add_theme_support: Every Feature Explained

Short answer
add_theme_support() tells WordPress which optional features your theme handles, such as post thumbnails, the document title, custom logos, and editor palettes. Call it in functions.php on the after_setup_theme hook, since the init hook is too late for some features, and check the result with current_theme_supports().
Key takeaways
- add_theme_support() registers one optional theme feature per call.
- Calls belong in functions.php on the after_setup_theme hook, not init.
- The reference lists 37 named features, from title-tag to wp-block-styles.
- html5 needs an array of markup types, and post-formats needs a list of formats.
- In block themes, theme.json settings take precedence over these calls.
- Check support with current_theme_supports() and remove it with remove_theme_support().
What is add_theme_support()?
add_theme_support() tells WordPress which optional features your theme handles, so core switches those features on for your theme.
The function registers theme support for a given feature. add_theme_support() states that it must be called in the theme functions.php file to work (checked November 2026).
Think of it as a switchboard. WordPress core holds many features that stay off until a theme asks for them, such as featured images, custom logos, and post formats. One call per feature turns each one on.
The function returns void on success and false on failure. add_theme_support() states that return value in its reference (checked November 2026).
Support is only a declaration. Turning on post thumbnails adds the Featured Image box in the editor, but your template must still print the image. The call gives permission, and the template does the work.
Where do you put add_theme_support() calls?
Put the calls in your theme functions.php file, inside a setup function hooked to after_setup_theme.
add_theme_support() states that if the call is attached to a hook, it must be after_setup_theme, and that the init hook may be too late for some features (checked November 2026).
The usual shape is a setup function with all the calls inside it, hooked once:
function mytheme_setup() {
add_theme_support( 'title-tag' );
add_theme_support( 'post-thumbnails' );
add_theme_support( 'html5', array( 'search-form', 'comment-form', 'comment-list', 'gallery', 'caption' ) );
}
add_action( 'after_setup_theme', 'mytheme_setup' );
The Block Editor Handbook shows the same shape for editor features, with a setup function that calls add_theme_support() and is hooked to after_setup_theme. Theme Support gives that pattern (checked November 2026).
Calling the function straight in functions.php without a hook also works, since the file loads early. The hook form is the common style because it groups all setup in one place.
The Post Formats page adds a timing warning: you must call the function before the init hook fires, and after_setup_theme is a good hook to use. Post Formats states that rule (checked November 2026).
Which features can you enable with add_theme_support()?
The function accepts 37 named features, from title-tag and post-thumbnails to editor-color-palette and html5.
add_theme_support() lists the likely core values, and counting them gives 37 names (checked November 2026). The list covers feed links, menus, widgets, post formats, custom headers and logos, editor palettes, and block tools.
Some features take no second argument. title-tag, post-thumbnails, automatic-feed-links, align-wide, and responsive-embeds all switch on with one line each.
Other features need an array that says how the feature should act. custom-logo takes height and width, html5 takes a list of markup types, and editor-color-palette takes a list of colors with a name, a slug, and a hex value.
A few names are read only and belong to other functions. The reference states that sidebars should use register_sidebar(), menus should use register_nav_menu(), and editor-style should use add_editor_style() instead. add_theme_support() lists those three as read-only parameters for current_theme_supports() (checked November 2026).
| Feature | What it does | Needs an argument? |
|---|---|---|
title-tag | Lets WordPress manage the document title | No |
post-thumbnails | Adds the Featured Image box | Optional, a list of post types |
html5 | Uses HTML5 markup for forms, lists, and galleries | Yes, a list of types |
custom-logo | Adds the site logo setting | Optional, height and width |
custom-header | Adds the header image setting | Optional, defaults array |
custom-background | Adds the background setting | Optional, defaults array |
post-formats | Enables post formats | Yes, a list of formats |
automatic-feed-links | Adds post and comment feed links | No |
editor-color-palette | Sets the editor color palette | Yes, a list of colors |
align-wide | Enables wide and full alignment for blocks | No |
responsive-embeds | Makes embeds resize with their container | No |
wp-block-styles | Loads opinionated core block styles | No |
How do you enable post thumbnails and the document title?
Enable post thumbnails with add_theme_support( 'post-thumbnails' ) and the document title with add_theme_support( 'title-tag' ).
For post thumbnails, you can pass a second argument with an array of the post types that should get the feature. add_theme_support() gives these three scoped forms (checked November 2026):
add_theme_support( 'post-thumbnails', array( 'post' ) );
add_theme_support( 'post-thumbnails', array( 'page' ) );
add_theme_support( 'post-thumbnails', array( 'post', 'movie' ) );
The first form enables thumbnails for posts only, the second for pages only, and the third for posts and a custom movie type. Without the second argument, all post types get the feature.
To print the thumbnail in a template, use the_post_thumbnail(). add_theme_support() states that call, and adds that you can check first with has_post_thumbnail() (checked November 2026).
For the title, the reference states that the feature enables plugins and themes to manage the document title tag, and that it should be used in place of the wp_title() function. add_theme_support() states that (checked November 2026).
With title-tag on, WordPress prints the title itself, and you should not print your own title tag in the theme header. That keeps the title in one place and lets SEO plugins adjust it.
How do you set up custom logos, headers, and backgrounds?
Register a custom logo, header, or background with one call each, passing sizes and defaults as an array.
The custom logo feature arrived in WordPress 4.5. add_theme_support() states that the feature was first introduced in Version 4.5 (checked November 2026).
A plain call switches the logo setting on:
add_theme_support( 'custom-logo' );
To set sizes, pass an array. The reference gives this example with a height of 480 and a width of 720:
add_theme_support( 'custom-logo', array(
'height' => 480,
'width' => 720,
) );
The reference also shows a fuller form with a height of 100, a width of 400, flexible height and width set to true, and the header text set to the site title and description. add_theme_support() gives those defaults (checked November 2026).
For a custom header, pass a defaults array with width, height, flexible height and width, and the default text color. add_theme_support() lists those defaults, including header-text set to true and uploads set to true (checked November 2026).
For a custom background, pass defaults for the image, position, size, repeat, and attachment. The reference lists defaults such as default-position-x set to left, default-repeat set to repeat, and default-attachment set to scroll. add_theme_support() gives that defaults array (checked November 2026).
A guide on how to edit the header in a block theme covers the block theme way to change the same area, where the header is a template part instead.
How do you control the block editor with add_theme_support()?
Use add_theme_support() to set the editor color palette, font sizes, gradients, and wide alignment for blocks.
For colors, register a palette with editor-color-palette. Theme Support gives an example palette with four colors, including “strong magenta” with the slug strong-magenta and the hex value #a156b4 (checked November 2026).
Each color needs three parts: a name that shows in a tooltip, a slug that builds the CSS class, and a color hex value.
The handbook states that the class name is built by adding has-, then the slug, then the context, such as .has-strong-magenta-color. Theme Support states that class rule (checked November 2026).
For font sizes, use editor-font-sizes with a list of names, sizes, and slugs. The handbook example lists Small at 12, Regular at 16, Large at 36, and Huge at 50. Theme Support gives those four sizes (checked November 2026).
For gradients, use editor-gradient-presets with a name, a gradient value, and a slug for each preset. The handbook example includes “Vivid cyan blue to vivid purple” with the slug vivid-cyan-blue-to-vivid-purple. Theme Support gives that preset (checked November 2026).
To let blocks use wide and full alignment, call add_theme_support( 'align-wide' ). The handbook states that blocks such as the image block can then define a wide or full alignment. Theme Support states that (checked November 2026).
To limit the editor, use the disable flags. The handbook states that disable-custom-colors keeps users to the palette you gave, and disable-custom-font-sizes keeps users to the sizes you gave. Theme Support states both flags (checked November 2026).
For opinionated core block styles in a classic theme, add wp-block-styles. The handbook states that for block themes, or themes that provide a theme.json file, this theme support is not recommended, and the block styles should go in theme.json instead. Theme Support states that guidance (checked November 2026).
How does add_theme_support() work in block themes and theme.json?
In block themes, theme.json sets most of these options instead, and its values take precedence over add_theme_support() calls.
The theme.json reference states that if the theme.json file contains any settings, these will take precedence over the values declared through add_theme_support(). Global Settings and Styles (theme.json) gives that precedence rule with a full equivalence table (checked November 2026).
That table maps the old flags to theme.json settings. For example, disable-custom-colors equals setting color.custom to false, editor-color-palette equals the color.palette list, and appearance-tools equals setting appearanceTools to true. Global Settings and Styles (theme.json) lists all of those mappings (checked November 2026).
WordPress 6.3 added two more opt-ins for non-block themes without theme.json: block link color tools and block border tools, through add_theme_support( 'link-color' ) and add_theme_support( 'border' ). Miscellaneous developer changes in WordPress 6.3 notes both opt-ins (checked November 2026).
Block themes are now a large share of the theme world. WordPress.org lists 1,985 block themes in its theme directory tag page. Block themes shows that count (checked November 2026).
A guide on block themes vs classic themes explains which kind of theme you have.
A guide on how to use theme.json covers the settings file that replaces most of these calls in block themes.
How do you check and remove theme support?
Check a feature with current_theme_supports() and switch it off with remove_theme_support().
The reference states that some parameters are read only and should only be used in the context of current_theme_supports(). add_theme_support() names that check function (checked November 2026).
Use the check in a template when a feature is optional. A template can ask whether the theme supports post thumbnails before it tries to print one, which keeps the markup clean on themes that never turned the feature on.
To remove a feature, call remove_theme_support() with the feature name. The Post Formats page states that calling remove_theme_support( 'post-formats' ) will remove it all together. Post Formats states that (checked November 2026).
Post formats also show how child themes interact with support. The reference states that in a child theme, add_theme_support( 'post-formats' ) will override the formats defined by the parent theme, not add to it. add_theme_support() states that override rule (checked November 2026).
The Post Formats page adds the fix: call the child theme support at a later priority than the parent theme, such as priority 11 on after_setup_theme. Post Formats gives that example (checked November 2026).
What mistakes should you avoid?
Avoid calling add_theme_support() on init, passing html5 without its array, and re-declaring a feature with a smaller argument list.
The init hook is too late for some features. The reference states that the init hook may be too late, and that the call must be in functions.php or on after_setup_theme. add_theme_support() states that timing rule (checked November 2026).
Do not call add_theme_support( 'html5' ) with no array. The reference code shows that WordPress warns when the array is missing, since the feature needs to know which markup types to change. add_theme_support() states that the array is required (checked November 2026).
Do not re-declare a feature with a shorter list and expect the lists to merge. For post formats, a second call replaces the first list, so a child theme that names only aside drops every format the parent named.
Do not mix wp-block-styles with theme.json. The handbook states that the two can clash, and that block styles belong in theme.json for themes that have one. Theme Support states that guidance (checked November 2026).
Do not assume a feature works because the call ran. Check the editor and the front of the site: the Featured Image box, the logo setting, the color palette, and the title tag all show whether the call took effect.
Frequently asked questions
Does add_theme_support() alone change what visitors see?
No. The call only declares that the theme handles the feature. For post thumbnails, the Featured Image box appears in the editor, but the template must still print the image with the_post_thumbnail(). The same split applies to logos and headers.
Why does my add_theme_support() call seem to do nothing?
Move the calls to a setup function hooked to after_setup_theme. The init hook is too late for some features, so calls placed there may be ignored. Calls placed straight in functions.php also work, since the file loads early.
Can a child theme change the post formats of its parent?
Yes, but the call replaces the parent list instead of adding to it. In a child theme, name every format you want to keep, and hook the call to after_setup_theme at a later priority, such as 11, so it runs after the parent setup.
Should I use add_theme_support() in a block theme?
Use theme.json instead. Its settings take precedence over add_theme_support() values, and the handbook advises against wp-block-styles for themes that provide theme.json. The old flags still map to theme.json settings, such as editor-color-palette to color.palette.
How do I enable HTML5 markup with add_theme_support()?
Call add_theme_support() with the feature name and an array of types, such as search-form, comment-form, comment-list, gallery, and caption. Calling it with no array triggers a warning, since WordPress needs to know which markup types to change.
How many features does add_theme_support() cover?
Yes. The reference lists 37 named features, from title-tag and post-thumbnails to editor-color-palette, html5, and wp-block-styles. A few names are read only and belong to other functions, such as register_sidebar() for sidebars.
Sources
- add_theme_support() WordPress Developer Resources
- Theme Support WordPress Developer Resources
- Global Settings & Styles (theme.json) WordPress Developer Resources
- Post Formats WordPress Developer Resources
- Miscellaneous developer changes in WordPress 6.3 Make WordPress Core
- Block themes WordPress.org
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.


