add_theme_support( string $feature, mixed $args ): void|false
- Since
- 2.9.0, 3.4.0, 3.6.0, 3.6.1, 3.9.0, 4.1.0, 4.5.0, 4.7.0, 5.0.0, 5.3.0, 5.3.0, 5.4.0, 5.5.0, 5.5.0, 5.6.0, 5.8.0, 5.8.0, 6.0.0, 6.1.0, 6.1.0, 6.3.0, 6.3.0, 6.5.0, 6.6.0
- Source
wp-includes/theme.php:2702
Registers theme support for a given feature.
Description
Must be called in the theme's functions.php file to work.
If attached to a hook, it must be 'after_setup_theme'.
The 'init' hook may be too late for some features.
Example usage:
add_theme_support( 'title-tag' );
add_theme_support( 'custom-logo', array(
'height' => 480,
'width' => 720,
) );Compatibility
- WordPress
- since 6.6.0
- PHP
- 7.4–8.6-dev
- 6.7.7
- 6.8.8
- 6.9.7
- 7.0.4
- 7.1.0
Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.
Parameters
$featurestring- The feature being added. Likely core values include:
- 'admin-bar'
- 'align-wide'
- 'appearance-tools'
- 'automatic-feed-links'
- 'block-templates'
- 'block-template-parts'
- 'border'
- 'core-block-patterns'
- 'custom-background'
- 'custom-header'
- 'custom-line-height'
- 'custom-logo'
- 'customize-selective-refresh-widgets'
- 'custom-spacing'
- 'custom-units'
- 'dark-editor-style'
- 'disable-custom-colors'
- 'disable-custom-font-sizes'
- 'disable-custom-gradients'
- 'disable-layout-styles'
- 'editor-color-palette'
- 'editor-gradient-presets'
- 'editor-font-sizes'
- 'editor-spacing-sizes'
- 'editor-styles'
- 'featured-content'
- 'html5'
- 'link-color'
- 'menus'
- 'post-formats'
- 'post-thumbnails'
- 'responsive-embeds'
- 'starter-content'
- 'title-tag'
- 'widgets'
- 'widgets-block-editor'
- 'wp-block-styles' $argsmixed- Optional extra arguments to pass along with certain features.
Return value
void|false- Void on success, false on failure.
Performance profile
How much work a call to add_theme_support() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.
- Cost class
- Trivial
- Scaling
- Constant
- Instructions
- 10–102
- Plugin surface
- None
- Called by
- 32
Touches nothing outside its own arguments.
No loop in the body: the same number of instructions runs whatever you pass in.
Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 373.
Nothing here hands control to plugin code.
32 places in core call this, so the cost is paid more often than your own code shows.
What it touches
- hookthird-party callbacks
do_action()one call below add_theme_support()
Further down the call graph this can also reach query, option, cache, serialize and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.
What one call costs · 14 distinct outcomes
One number would be a lie: the work depends on which branch runs. These are every distinct cost add_theme_support() can have, taken from its control-flow graph on PHP 8.5.
| When | Instructions | Calls it makes |
|---|---|---|
| always | 10 | add_theme_support() |
| always | 11–20 | get_theme_support() |
!isset($_wp_theme_features) | 15–80 | none |
| always | 16–29 | __(), _doing_it_wrong() |
!empty($args) && isset($_wp_theme_features) | 25 | array_merge() |
| always | 26–38 | array_intersect_key(), wp_parse_args() |
isset($args) | 28 | get_post_format_slugs(), array_keys(), array_intersect() |
isset($args) && isset($_wp_theme_features) | 33 | get_theme_support(), array_merge(), array_unique() |
isset($_wp_theme_features) | 33–39 | __(), _doing_it_wrong(), array_merge() |
$args !== true && !isset($_wp_theme_features) | 50–86 | define() |
$args !== true && !isset($_wp_theme_features) | 56–90 | define(), define() |
$args !== true && !isset($_wp_theme_features) | 62–94 | define(), define(), define() |
2 further outcomes, up to 102 instructions
$args !== true && !isset($_wp_theme_features) && !defined('NO_HEADER_TEXT') | 69–98 | define(), define(), define(), define() |
$args !== true && !isset($_wp_theme_features) && !defined('NO_HEADER_TEXT') && !defined('HEADER_IMAGE_WIDTH') && !defined('HEADER_IMAGE_HEIGHT') && !defined('HEADER_TEXTCOLOR') && !defined('HEADER_IMAGE') | 76–102 | define(), define(), define(), define(), define() |
This body has more branch combinations than are worth enumerating, so the table covers the outcomes found first rather than every one that exists.
Across PHP versions
| PHP | Compiled | Executed | Branches | Notes |
|---|---|---|---|---|
| 8.6-dev | 373 | 10–102 | 54 | |
| 8.5 | 373 | 10–102 | 54 | |
| 8.4 | 373 | 10–102 | 54 | |
| 8.3 | 373 | 10–102 | 54 | |
| 8.2 | 373 | 10–102 | 54 | 1 more instruction than PHP 8.1 |
| 8.1 | 372 | 10–102 | 54 | |
| 7.4 | 372 | 10–102 | 54 |
An instruction is not a fixed amount of time, so a matching count is not necessarily the same speed; what it rules out is a difference in the work itself.
Uses · 7
- get_theme_support()Gets the theme support arguments passed when registering that support.
- get_post_format_slugs()Retrieves the array of post format slugs.
- _doing_it_wrong()Marks something as being incorrectly called.
- __()Retrieves the translation of $text.
- wp_parse_args()Merges user defined arguments into defaults array.
- add_theme_support()Registers theme support for a given feature.
- did_action()Retrieves the number of times an action has been fired during the current request.
Used by · 32
- _add_default_theme_supports()Adds default theme supports for block themes when the 'after_setup_theme' action fires.
- _custom_header_background_just_in_time()Registers the internal custom header and background routines.
- _remove_theme_support()Do not use. Removes theme support internally without knowledge of those not used by themes directly.
- add_custom_background()Add callbacks for background image display.
- add_custom_image_header()Add callbacks for image header display.
- add_editor_style()Adds callback for custom TinyMCE editor stylesheets.
- add_theme_support()Registers theme support for a given feature.
- automatic_feed_links()Enable/disable automatic general feed link outputting.
- register_nav_menus()Registers navigation menu locations for a theme.
- register_sidebar()Builds the definition for a single sidebar and returns the ID.
- twenty_twenty_one_setup()Sets up theme defaults and registers support for various WordPress features.
- twentyeleven_setup()Sets up theme defaults and registers support for various WordPress features.
Show all 32
- twentyfifteen_custom_header_setup()Sets up the WordPress core custom header feature.
- twentyfifteen_setup()Sets up theme defaults and registers support for various WordPress features.
- twentyfourteen_custom_header_setup()Sets up the WordPress core custom header settings.
- twentyfourteen_setup()Twenty Fourteen setup.
- twentynineteen_setup()Sets up theme defaults and registers support for various WordPress features.
- twentyseventeen_custom_header_setup()Sets up the WordPress core custom header feature.
- twentyseventeen_setup()Sets up theme defaults and registers support for various WordPress features.
- twentysixteen_custom_header_and_background()Sets up the WordPress core custom header and custom background features.
- twentysixteen_setup()Sets up theme defaults and registers support for various WordPress features.
- twentyten_setup()Sets up theme defaults and registers support for various WordPress features.
- twentythirteen_custom_header_setup()Sets up the WordPress core custom header arguments and settings.
- twentythirteen_setup()Twenty Thirteen setup.
- twentytwelve_custom_header_setup()Sets up the WordPress core custom header arguments and settings.
- twentytwelve_setup()Twenty Twelve setup.
- twentytwenty_block_editor_settings()Block Editor Settings.
- twentytwenty_theme_support()Sets up theme defaults and registers support for various WordPress features.
- twentytwentyfive_post_format_setup()Adds theme support for post formats.
- twentytwentytwo_support()Sets up theme defaults and registers support for various WordPress features.
- wp_enable_block_templates()Enables the block templates (editor mode) for themes with theme.json by default.
- wp_setup_widgets_block_editor()Enables the widgets block editor. This is hooked into 'after_setup_theme' so that the block editor is enabled by default but can be disabled by themes.
Source code
function add_theme_support( $feature, ...$args ) { global $_wp_theme_features; if ( ! $args ) { $args = true; } switch ( $feature ) { case 'post-thumbnails': // All post types are already supported. if ( true === get_theme_support( 'post-thumbnails' ) ) { return; } /* * Merge post types with any that already declared their support * for post thumbnails. */ if ( isset( $args[0] ) && is_array( $args[0] ) && isset( $_wp_theme_features['post-thumbnails'] ) ) { $args[0] = array_unique( array_merge( $_wp_theme_features['post-thumbnails'][0], $args[0] ) ); } break; case 'post-formats': if ( isset( $args[0] ) && is_array( $args[0] ) ) { $post_formats = get_post_format_slugs(); unset( $post_formats['standard'] ); $args[0] = array_intersect( $args[0], array_keys( $post_formats ) ); } else { _doing_it_wrong( "add_theme_support( 'post-formats' )", __( 'You need to pass an array of post formats.' ), '5.6.0' ); return false; } break; case 'html5': // You can't just pass 'html5', you need to pass an array of types. if ( empty( $args[0] ) || ! is_array( $args[0] ) ) { _doing_it_wrong( "add_theme_support( 'html5' )", __( 'You need to pass an array of types.' ), '3.6.1' ); if ( ! empty( $args[0] ) && ! is_array( $args[0] ) ) { return false; } // Build an array of types for back-compat. $args = array( 0 => array( 'comment-list', 'comment-form', 'search-form' ) ); } // Calling 'html5' again merges, rather than overwrites. if ( isset( $_wp_theme_features['html5'] ) ) { $args[0] = array_merge( $_wp_theme_features['html5'][0], $args[0] ); } break; case 'custom-logo': if ( true === $args ) { $args = array( 0 => array() ); } $defaults = array( 'width' => null, 'height' => null, 'flex-width' => false, 'flex-height' => false, 'header-text' => '', 'unlink-homepage-logo' => false, ); $args[0] = wp_parse_args( array_intersect_key( $args[0], $defaults ), $defaults ); // Allow full flexibility if no size is specified. if ( is_null( $args[0]['width'] ) && is_null( $args[0]['height'] ) ) { $args[0]['flex-width'] = true;Changelog
Introduced in 2.9.0. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
6.6.0
The
editor-spacing-sizes feature was added.from the docblock6.5.0
The
appearance-tools feature enables a few design tools for blocks, see WP_Theme_JSON::APPEARANCE_TOOLS_OPT_INS for a complete list.from the docblock6.3.0
The
border feature allows themes without theme.json to add border styles to blocks.from the docblock6.3.0
The
link-color feature allows to enable the link color setting.from the docblock6.1.0
The
disable-layout-styles feature disables the default layout styles.from the docblock6.1.0
The
block-template-parts feature allows to edit any reusable template part from site editor.from the docblock6.0.0
The
html5 feature warns if no array is passed as the second parameter.from the docblock5.8.0
The
block-templates feature indicates whether a theme uses block-based templates.from the docblock5.8.0
The
widgets-block-editor feature enables the Widgets block editor.from the docblock5.6.0
The
post-formats feature warns if no array is passed as the second parameter.from the docblock5.5.0
The
custom-logo feature now also accepts 'unlink-homepage-logo'.from the docblock5.5.0
The
core-block-patterns feature was added and is enabled by default.from the docblock5.4.0
The
disable-custom-gradients feature limits to default gradients or gradients added through editor-gradient-presets theme support.from the docblock5.3.0
Formalized the existing and already documented
...$args parameter by adding it to the function signature.from the docblock5.3.0
The
html5 feature now also accepts 'script' and 'style'.from the docblock5.0.0
The
responsive-embeds, align-wide, dark-editor-style, disable-custom-colors, disable-custom-font-sizes, editor-color-palette, editor-font-sizes, editor-styles, and wp-block-styles features were added.from the docblock4.7.0
The
starter-content feature was added.from the docblock4.5.0
The
customize-selective-refresh-widgets feature was added.from the docblock4.1.0
The
title-tag feature was added.from the docblock3.9.0
The
html5 feature now also accepts 'gallery' and 'caption'.from the docblock3.6.1
The
html5 feature requires an array of types to be passed. Defaults to 'comment-list', 'comment-form', 'search-form' for backward compatibility.from the docblock3.6.0
The
html5 feature was added.from the docblock3.4.0
The
custom-header-uploads feature was deprecated.from the docblock2.9.0
Introduced.from the docblock
About this page
- Parsed data
- Generated from the wordpress-develop 6.9.7 tag, from
src/wp-includes/theme.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it. - Corrections
- Something wrong on this page? Report it and it gets fixed in the next regeneration.