add_theme_support( string $feature, mixed $args ): void|false

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,
) );

Parameters

$featurestringrequired
The feature being added. Likely core values include:
  • 'admin-bar'
  • 'align-wide'
  • 'automatic-feed-links'
  • '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'
  • 'editor-color-palette'
  • 'editor-gradient-presets'
  • 'editor-font-sizes'
  • 'editor-styles'
  • 'featured-content'
  • 'html5'
  • 'menus'
  • 'post-formats'
  • 'post-thumbnails'
  • 'responsive-embeds'
  • 'starter-content'
  • 'title-tag'
  • 'wp-block-styles'
  • 'widgets'
  • 'widgets-block-editor'
$argsmixedoptional
Optional extra arguments to pass along with certain features.

Return

void|false Void on success, false on failure.

More Information

Features

Post Formats

This feature enables Post Formats support for a theme. When using child themes, be aware that

add_theme_support( 'post-formats' )

will override the formats as defined by the parent theme, not add to it.

To enable the specific formats (see supported formats at Post Formats), use:

add_theme_support( 'post-formats', array( 'aside', 'gallery' ) );

To check if there is a ‘quote’ post format assigned to the post, use has_post_format() :

// In your theme single.php, page.php or custom post type
if ( has_post_format( 'quote' ) ) {
echo 'This is a quote.';
}

Post Thumbnails

This feature enables Post Thumbnails support for a theme. Note that you can optionally pass a second argument, $args, with an array of the Post Types for which you want to enable this feature.

add_theme_support( 'post-thumbnails' );
add_theme_support( 'post-thumbnails', array( 'post' ) );          // Posts only
add_theme_support( 'post-thumbnails', array( 'page' ) );          // Pages only
add_theme_support( 'post-thumbnails', array( 'post', 'movie' ) ); // Posts and Movies

This feature must be called before the ‘init’ hook is fired. That means it needs to be placed directly into functions.php or within a function attached to the ‘after_setup_theme’ hook. For custom post types, you can also add post thumbnails using the register_post_type() function as well.

To display thumbnails in themes index.php or single.php or custom templates, use:

the_post_thumbnail();

To check if there is a post thumbnail assigned to the post before displaying it, use:

if ( has_post_thumbnail() ) {
the_post_thumbnail();
}

Custom Background

This feature enables Custom_Backgrounds support for a theme.

add_theme_support( 'custom-background' );

Note that you can add default arguments using:

$defaults = array(
'default-image'          => '',
'default-preset'         => 'default', // 'default', 'fill', 'fit', 'repeat', 'custom'
'default-position-x'     => 'left',    // 'left', 'center', 'right'
'default-position-y'     => 'top',     // 'top', 'center', 'bottom'
'default-size'           => 'auto',    // 'auto', 'contain', 'cover'
'default-repeat'         => 'repeat',  // 'repeat-x', 'repeat-y', 'repeat', 'no-repeat'
'default-attachment'     => 'scroll',  // 'scroll', 'fixed'
'default-color'          => '',
'wp-head-callback'       => '_custom_background_cb',
'admin-head-callback'    => '',
'admin-preview-callback' => '',
);
add_theme_support( 'custom-background', $defaults );

Custom Header

This feature enables Custom_Headers support for a theme.

add_theme_support( 'custom-header' );

Note that you can add default arguments using:

$defaults = array(
'default-image'          => '',
'random-default'         => false,
'width'                  => 0,
'height'                 => 0,
'flex-height'            => false,
'flex-width'             => false,
'default-text-color'     => '',
'header-text'            => true,
'uploads'                => true,
'wp-head-callback'       => '',
'admin-head-callback'    => '',
'admin-preview-callback' => '',
'video'                  => false,
'video-active-callback'  => 'is_front_page',
);
add_theme_support( 'custom-header', $defaults );

Custom Logo

This feature, first introduced in Version_4.5, enables Theme_Logo support for a theme.

add_theme_support( 'custom-logo' );

Note that you can add default arguments using:

add_theme_support( 'custom-logo', array(
'height'               => 100,
'width'                => 400,
'flex-height'          => true,
'flex-width'           => true,
'header-text'          => array( 'site-title', 'site-description' ),
'unlink-homepage-logo' => true,
) );

Feed Links

This feature enables Automatic Feed Links for post and comment in the head. This should be used in place of the deprecated automatic_feed_links() function.

add_theme_support( 'automatic-feed-links' );

HTML5

This feature allows the use of HTML5 markup for the search forms, comment forms, comment lists, gallery, and caption.

add_theme_support( 'html5', array( 'comment-list', 'comment-form', 'search-form', 'gallery', 'caption', 'style', 'script' ) );

Title Tag

This feature enables plugins and themes to manage the document title tag. This should be used in place of wp_title() function.

add_theme_support( 'title-tag' );

Customize Selective Refresh Widgets

This feature enables Selective Refresh for Widgets being managed within the Customizer. This feature became available in WordPress 4.5. For more on why and how Selective Refresh works read Implementing Selective Refresh Support for Widgets.

add_theme_support( 'customize-selective-refresh-widgets' );

Multisite

To show the “Featured Image” meta box in Multisite installation, make sure you update the allowed upload file types, in Network Admin, Network Admin Settings SubPanel#Upload_Settings, Media upload buttons options. Default is jpg jpeg png gif mp3 mov avi wmv midi mid pdf.

Other Notes

The following parameters are read only, and should only be used in the context of current_theme_supports():

Source

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;
				$args[0]['flex-height'] = true;
			}
			break;

		case 'custom-header-uploads':
			return add_theme_support( 'custom-header', array( 'uploads' => true ) );

		case 'custom-header':
			if ( true === $args ) {
				$args = array( 0 => array() );
			}

			$defaults = array(
				'default-image'          => '',
				'random-default'         => false,
				'width'                  => 0,
				'height'                 => 0,
				'flex-height'            => false,
				'flex-width'             => false,
				'default-text-color'     => '',
				'header-text'            => true,
				'uploads'                => true,
				'wp-head-callback'       => '',
				'admin-head-callback'    => '',
				'admin-preview-callback' => '',
				'video'                  => false,
				'video-active-callback'  => 'is_front_page',
			);

			$jit = isset( $args[0]['__jit'] );
			unset( $args[0]['__jit'] );

			/*
			 * Merge in data from previous add_theme_support() calls.
			 * The first value registered wins. (A child theme is set up first.)
			 */
			if ( isset( $_wp_theme_features['custom-header'] ) ) {
				$args[0] = wp_parse_args( $_wp_theme_features['custom-header'][0], $args[0] );
			}

			/*
			 * Load in the defaults at the end, as we need to insure first one wins.
			 * This will cause all constants to be defined, as each arg will then be set to the default.
			 */
			if ( $jit ) {
				$args[0] = wp_parse_args( $args[0], $defaults );
			}

			/*
			 * If a constant was defined, use that value. Otherwise, define the constant to ensure
			 * the constant is always accurate (and is not defined later,  overriding our value).
			 * As stated above, the first value wins.
			 * Once we get to wp_loaded (just-in-time), define any constants we haven't already.
			 * Constants are lame. Don't reference them. This is just for backward compatibility.
			 */

			if ( defined( 'NO_HEADER_TEXT' ) ) {
				$args[0]['header-text'] = ! NO_HEADER_TEXT;
			} elseif ( isset( $args[0]['header-text'] ) ) {
				define( 'NO_HEADER_TEXT', empty( $args[0]['header-text'] ) );
			}

			if ( defined( 'HEADER_IMAGE_WIDTH' ) ) {
				$args[0]['width'] = (int) HEADER_IMAGE_WIDTH;
			} elseif ( isset( $args[0]['width'] ) ) {
				define( 'HEADER_IMAGE_WIDTH', (int) $args[0]['width'] );
			}

			if ( defined( 'HEADER_IMAGE_HEIGHT' ) ) {
				$args[0]['height'] = (int) HEADER_IMAGE_HEIGHT;
			} elseif ( isset( $args[0]['height'] ) ) {
				define( 'HEADER_IMAGE_HEIGHT', (int) $args[0]['height'] );
			}

			if ( defined( 'HEADER_TEXTCOLOR' ) ) {
				$args[0]['default-text-color'] = HEADER_TEXTCOLOR;
			} elseif ( isset( $args[0]['default-text-color'] ) ) {
				define( 'HEADER_TEXTCOLOR', $args[0]['default-text-color'] );
			}

			if ( defined( 'HEADER_IMAGE' ) ) {
				$args[0]['default-image'] = HEADER_IMAGE;
			} elseif ( isset( $args[0]['default-image'] ) ) {
				define( 'HEADER_IMAGE', $args[0]['default-image'] );
			}

			if ( $jit && ! empty( $args[0]['default-image'] ) ) {
				$args[0]['random-default'] = false;
			}

			/*
			 * If headers are supported, and we still don't have a defined width or height,
			 * we have implicit flex sizes.
			 */
			if ( $jit ) {
				if ( empty( $args[0]['width'] ) && empty( $args[0]['flex-width'] ) ) {
					$args[0]['flex-width'] = true;
				}
				if ( empty( $args[0]['height'] ) && empty( $args[0]['flex-height'] ) ) {
					$args[0]['flex-height'] = true;
				}
			}

			break;

		case 'custom-background':
			if ( true === $args ) {
				$args = array( 0 => array() );
			}

			$defaults = array(
				'default-image'          => '',
				'default-preset'         => 'default',
				'default-position-x'     => 'left',
				'default-position-y'     => 'top',
				'default-size'           => 'auto',
				'default-repeat'         => 'repeat',
				'default-attachment'     => 'scroll',
				'default-color'          => '',
				'wp-head-callback'       => '_custom_background_cb',
				'admin-head-callback'    => '',
				'admin-preview-callback' => '',
			);

			$jit = isset( $args[0]['__jit'] );
			unset( $args[0]['__jit'] );

			// Merge in data from previous add_theme_support() calls. The first value registered wins.
			if ( isset( $_wp_theme_features['custom-background'] ) ) {
				$args[0] = wp_parse_args( $_wp_theme_features['custom-background'][0], $args[0] );
			}

			if ( $jit ) {
				$args[0] = wp_parse_args( $args[0], $defaults );
			}

			if ( defined( 'BACKGROUND_COLOR' ) ) {
				$args[0]['default-color'] = BACKGROUND_COLOR;
			} elseif ( isset( $args[0]['default-color'] ) || $jit ) {
				define( 'BACKGROUND_COLOR', $args[0]['default-color'] );
			}

			if ( defined( 'BACKGROUND_IMAGE' ) ) {
				$args[0]['default-image'] = BACKGROUND_IMAGE;
			} elseif ( isset( $args[0]['default-image'] ) || $jit ) {
				define( 'BACKGROUND_IMAGE', $args[0]['default-image'] );
			}

			break;

		// Ensure that 'title-tag' is accessible in the admin.
		case 'title-tag':
			// Can be called in functions.php but must happen before wp_loaded, i.e. not in header.php.
			if ( did_action( 'wp_loaded' ) ) {
				_doing_it_wrong(
					"add_theme_support( 'title-tag' )",
					sprintf(
						/* translators: 1: title-tag, 2: wp_loaded */
						__( 'Theme support for %1$s should be registered before the %2$s hook.' ),
						'<code>title-tag</code>',
						'<code>wp_loaded</code>'
					),
					'4.1.0'
				);

				return false;
			}
	}

	$_wp_theme_features[ $feature ] = $args;
}

Changelog

VersionDescription
6.0.0The html5 feature warns if no array is passed as the second parameter.
5.8.0The widgets-block-editor feature enables the Widgets block editor.
5.6.0The post-formats feature warns if no array is passed as the second parameter.
5.5.0The custom-logo feature now also accepts 'unlink-homepage-logo'.
5.3.0Formalized the existing and already documented ...$args parameter by adding it to the function signature.
5.0.0The 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.
4.7.0The starter-content feature was added.
4.5.0The customize-selective-refresh-widgets feature was added.
4.1.0The title-tag feature was added.
3.9.0The html5 feature now also accepts 'gallery' and 'caption'.
3.6.1The html5 feature requires an array of types to be passed. Defaults to 'comment-list', 'comment-form', 'search-form' for backward compatibility.
3.6.0The html5 feature was added.
3.4.0The custom-header-uploads feature was deprecated.
2.9.0Introduced.
Show 9 moreShow less

User Contributed Notes

  1. Skip to note 15 content
    /**
     * Essential theme supports
     * */
    function theme_setup(){
        /** automatic feed link*/
        add_theme_support( 'automatic-feed-links' );
    
        /** tag-title **/
        add_theme_support( 'title-tag' );
    
        /** post formats */
        $post_formats = array('aside','image','gallery','video','audio','link','quote','status');
        add_theme_support( 'post-formats', $post_formats);
    
        /** post thumbnail **/
        add_theme_support( 'post-thumbnails' );
    
        /** HTML5 support **/
        add_theme_support( 'html5', array( 'comment-list', 'comment-form', 'search-form', 'gallery', 'caption' ) );
    
        /** refresh widgest **/
        add_theme_support( 'customize-selective-refresh-widgets' );
    
        /** custom background **/
        $bg_defaults = array(
            'default-image'          => '',
            'default-preset'         => 'default',
            'default-size'           => 'cover',
            'default-repeat'         => 'no-repeat',
            'default-attachment'     => 'scroll',
        );
        add_theme_support( 'custom-background', $bg_defaults );
    
        /** custom header **/
        $header_defaults = array(
            'default-image'          => '',
            'width'                  => 300,
            'height'                 => 60,
            'flex-height'            => true,
            'flex-width'             => true,
            'default-text-color'     => '',
            'header-text'            => true,
            'uploads'                => true,
        );
        add_theme_support( 'custom-header', $header_defaults );
    
        /** custom log **/
        add_theme_support( 'custom-logo', array(
            'height'      => 60,
            'width'       => 400,
            'flex-height' => true,
            'flex-width'  => true,
            'header-text' => array( 'site-title', 'site-description' ),
        ) );
    
    
    
    }
    add_action('after_setup_theme','theme_setup');
  2. Skip to note 18 content

    From WP 5.3, add_theme_support('html5', ['script', 'style']); removes type="text/javascript" and type=”text/css” from enqueued scripts and styles.

    See https://make.wordpress.org/core/2019/10/15/miscellaneous-developer-focused-changes-in-5-3/ – HTML5 Supports Argument for Script and Style Tags

  3. Skip to note 21 content
  4. Skip to note 23 content

    Declare support for navigation widgets markup.

    add_theme_support( 'html5', array( 'navigation-widgets' ) );

    “Theme developers are highly encouraged to utilize this improvement in their themes. This new theme support feature is an easy way to improve semantics and accessibility in all of the sites using your theme.”

  5. Skip to note 24 content

    “default-color” for custom background doesn’t work

    Solution is to define your own stylesheet class and add the CSS class to the body tag.

  6. Skip to note 27 content

    If you enable 'responsive-embeds', these are responsive classes you can use (.wp-embed-aspect-21-9) etc. on embedded block (like e.g. youtube):

    .wp-embed-responsive .wp-embed-aspect-21-9 .wp-block-embed__wrapper::before {
      padding-top: 42.85%;
    }
    .wp-embed-responsive .wp-embed-aspect-18-9 .wp-block-embed__wrapper::before {
      padding-top: 50%;
    }
    .wp-embed-responsive .wp-embed-aspect-16-9 .wp-block-embed__wrapper::before {
      padding-top: 56.25%;
    }
    .wp-embed-responsive .wp-embed-aspect-4-3 .wp-block-embed__wrapper::before {
      padding-top: 75%;
    }
    .wp-embed-responsive .wp-embed-aspect-1-1 .wp-block-embed__wrapper::before {
      padding-top: 100%;
    }
    .wp-embed-responsive .wp-embed-aspect-9-16 .wp-block-embed__wrapper::before {
      padding-top: 177.77%;
    }
    .wp-embed-responsive .wp-embed-aspect-1-2 .wp-block-embed__wrapper::before {
      padding-top: 200%;
    }
  7. Skip to note 28 content

    Starter Content #

    Defines and registers starter content to showcase themes on new sites.

    add_theme_support( 'starter-content', array(
        // Place widgets in the desired locations (such as sidebar or footer).
        // Example widgets: archives, calendar, categories, meta, recent-comments, recent-posts, 
        //                  search, text_business_info, text_about
        'widgets'     => array( 'sidebar-1' => array( 'search', 'categories', 'meta'), ),
        // Specify pages to create, and optionally add custom thumbnails to them.
        // Note: For thumbnails, use attachment symbolic references in {{double-curly-braces}}.
        // Post options: post_type, post_title, post_excerpt, post_name (slug), post_content, 
        //               menu_order, comment_status, thumbnail (featured image ID), and template
        'posts'       => array( 'home', 'about', 'blog' => array( 'thumbnail' => '{{image-cafe}}' ), ),
        // Create custom image attachments used as post thumbnails for pages.
        // Note: You can reference these attachment IDs in the posts section above. Example: {{image-cafe}}
        'attachments' => array( 'image-cafe' => array( 'post_title' => 'Cafe', 'file' => 'assets/images/cafe.jpg' ), ),
        // Assign options defaults, such as front page settings.
        // The 'show_on_front' value can be 'page' to show a specified page, or 'posts' to show your latest posts.
        // Note: Use page ID symbolic references from the posts section above wrapped in {{double-curly-braces}}.
        'options'     => array( 'show_on_front'  => 'page', 'page_on_front' => '{{home}}', 'page_for_posts' => '{{blog}}', ),
    	// Set the theme mods.
        'theme_mods'  => array( 'panel_1' => '{{about}}' ),
    	// Set up nav menus.
        'nav_menus'   => array( 'top' => array( 'name' => 'Top Menu', 'items' => array( 'link_home', 'page_about', 'page_blog' )), ),
    ) );

    For full examples of each option, you can reference the Twenty Seventeen theme’s functions.php:

    https://github.com/xwp/wordpress-develop/blob/master/src/wp-content/themes/twentyseventeen/functions.php#L117

You must log in before being able to contribute a note or feedback.