add_theme_support

Registers theme support for a given feature.

Description

(void|bool) add_theme_support( (string) $feature ); 

Must be called in the theme's functions.php file to work. If attached to a hook, it must be . The hook may be too late for some features.

Returns (void|bool)

False on failure, void otherwise.

Parameters (1)

0. $feature (string)
The feature being added. Likely core values include post-formats,, post-thumbnails, html5, custom-logo, custom-header-uploads, custom-header, custom-background, title-tag, starter-content, etc.

Usage

  1. if ( !function_exists( 'add_theme_support' ) ) { 
  2.     require_once ABSPATH . WPINC . '/theme.php'; 
  3. } 
  4. $feature = ''; 
  5.   
  6. // NOTICE! Understand what this does before running. 
  7. $result = add_theme_support($feature); 
  8.     

Defined (1)

The function is defined in the following location(s).

/wp-includes/theme.php  
  1. function add_theme_support( $feature ) { 
  2.     global $_wp_theme_features; 
  3.  
  4.     if ( func_num_args() == 1 ) 
  5.         $args = true; 
  6.     else 
  7.         $args = array_slice( func_get_args(), 1 ); 
  8.  
  9.     switch ( $feature ) { 
  10.         case 'post-thumbnails': 
  11.             // All post types are already supported. 
  12.             if ( true === get_theme_support( 'post-thumbnails' ) ) { 
  13.                 return; 
  14.             } 
  15.  
  16.             /** 
  17.              * Merge post types with any that already declared their support 
  18.              * for post thumbnails. 
  19.              */ 
  20.             if ( is_array( $args[0] ) && isset( $_wp_theme_features['post-thumbnails'] ) ) { 
  21.                 $args[0] = array_unique( array_merge( $_wp_theme_features['post-thumbnails'][0], $args[0] ) ); 
  22.             } 
  23.  
  24.             break; 
  25.  
  26.         case 'post-formats' : 
  27.             if ( is_array( $args[0] ) ) { 
  28.                 $post_formats = get_post_format_slugs(); 
  29.                 unset( $post_formats['standard'] ); 
  30.  
  31.                 $args[0] = array_intersect( $args[0], array_keys( $post_formats ) ); 
  32.             } 
  33.             break; 
  34.  
  35.         case 'html5' : 
  36.             // You can't just pass 'html5', you need to pass an array of types. 
  37.             if ( empty( $args[0] ) ) { 
  38.                 // Build an array of types for back-compat. 
  39.                 $args = array( 0 => array( 'comment-list', 'comment-form', 'search-form' ) ); 
  40.             } elseif ( ! is_array( $args[0] ) ) { 
  41.                 _doing_it_wrong( "add_theme_support( 'html5' )", __( 'You need to pass an array of types.' ), '3.6.1' ); 
  42.                 return false; 
  43.             } 
  44.  
  45.             // Calling 'html5' again merges, rather than overwrites. 
  46.             if ( isset( $_wp_theme_features['html5'] ) ) 
  47.                 $args[0] = array_merge( $_wp_theme_features['html5'][0], $args[0] ); 
  48.             break; 
  49.  
  50.         case 'custom-logo': 
  51.             if ( ! is_array( $args ) ) { 
  52.                 $args = array( 0 => array() ); 
  53.             } 
  54.             $defaults = array( 
  55.                 'width' => null,  
  56.                 'height' => null,  
  57.                 'flex-width' => false,  
  58.                 'flex-height' => false,  
  59.                 'header-text' => '',  
  60.  ); 
  61.             $args[0] = wp_parse_args( array_intersect_key( $args[0], $defaults ), $defaults ); 
  62.  
  63.             // Allow full flexibility if no size is specified. 
  64.             if ( is_null( $args[0]['width'] ) && is_null( $args[0]['height'] ) ) { 
  65.                 $args[0]['flex-width'] = true; 
  66.                 $args[0]['flex-height'] = true; 
  67.             } 
  68.             break; 
  69.  
  70.         case 'custom-header-uploads' : 
  71.             return add_theme_support( 'custom-header', array( 'uploads' => true ) ); 
  72.  
  73.         case 'custom-header' : 
  74.             if ( ! is_array( $args ) ) 
  75.                 $args = array( 0 => array() ); 
  76.  
  77.             $defaults = array( 
  78.                 'default-image' => '',  
  79.                 'random-default' => false,  
  80.                 'width' => 0,  
  81.                 'height' => 0,  
  82.                 'flex-height' => false,  
  83.                 'flex-width' => false,  
  84.                 'default-text-color' => '',  
  85.                 'header-text' => true,  
  86.                 'uploads' => true,  
  87.                 'wp-head-callback' => '',  
  88.                 'admin-head-callback' => '',  
  89.                 'admin-preview-callback' => '',  
  90.                 'video' => false,  
  91.                 'video-active-callback' => 'is_front_page',  
  92.  ); 
  93.  
  94.             $jit = isset( $args[0]['__jit'] ); 
  95.             unset( $args[0]['__jit'] ); 
  96.  
  97.             // Merge in data from previous add_theme_support() calls. 
  98.             // The first value registered wins. (A child theme is set up first.) 
  99.             if ( isset( $_wp_theme_features['custom-header'] ) ) 
  100.                 $args[0] = wp_parse_args( $_wp_theme_features['custom-header'][0], $args[0] ); 
  101.  
  102.             // Load in the defaults at the end, as we need to insure first one wins. 
  103.             // This will cause all constants to be defined, as each arg will then be set to the default. 
  104.             if ( $jit ) 
  105.                 $args[0] = wp_parse_args( $args[0], $defaults ); 
  106.  
  107.             // If a constant was defined, use that value. Otherwise, define the constant to ensure 
  108.             // the constant is always accurate (and is not defined later, overriding our value). 
  109.             // As stated above, the first value wins. 
  110.             // Once we get to wp_loaded (just-in-time), define any constants we haven't already. 
  111.             // Constants are lame. Don't reference them. This is just for backward compatibility. 
  112.  
  113.             if ( defined( 'NO_HEADER_TEXT' ) ) 
  114.                 $args[0]['header-text'] = ! NO_HEADER_TEXT; 
  115.             elseif ( isset( $args[0]['header-text'] ) ) 
  116.                 define( 'NO_HEADER_TEXT', empty( $args[0]['header-text'] ) ); 
  117.  
  118.             if ( defined( 'HEADER_IMAGE_WIDTH' ) ) 
  119.                 $args[0]['width'] = (int) HEADER_IMAGE_WIDTH; 
  120.             elseif ( isset( $args[0]['width'] ) ) 
  121.                 define( 'HEADER_IMAGE_WIDTH', (int) $args[0]['width'] ); 
  122.  
  123.             if ( defined( 'HEADER_IMAGE_HEIGHT' ) ) 
  124.                 $args[0]['height'] = (int) HEADER_IMAGE_HEIGHT; 
  125.             elseif ( isset( $args[0]['height'] ) ) 
  126.                 define( 'HEADER_IMAGE_HEIGHT', (int) $args[0]['height'] ); 
  127.  
  128.             if ( defined( 'HEADER_TEXTCOLOR' ) ) 
  129.                 $args[0]['default-text-color'] = HEADER_TEXTCOLOR; 
  130.             elseif ( isset( $args[0]['default-text-color'] ) ) 
  131.                 define( 'HEADER_TEXTCOLOR', $args[0]['default-text-color'] ); 
  132.  
  133.             if ( defined( 'HEADER_IMAGE' ) ) 
  134.                 $args[0]['default-image'] = HEADER_IMAGE; 
  135.             elseif ( isset( $args[0]['default-image'] ) ) 
  136.                 define( 'HEADER_IMAGE', $args[0]['default-image'] ); 
  137.  
  138.             if ( $jit && ! empty( $args[0]['default-image'] ) ) 
  139.                 $args[0]['random-default'] = false; 
  140.  
  141.             // If headers are supported, and we still don't have a defined width or height,  
  142.             // we have implicit flex sizes. 
  143.             if ( $jit ) { 
  144.                 if ( empty( $args[0]['width'] ) && empty( $args[0]['flex-width'] ) ) 
  145.                     $args[0]['flex-width'] = true; 
  146.                 if ( empty( $args[0]['height'] ) && empty( $args[0]['flex-height'] ) ) 
  147.                     $args[0]['flex-height'] = true; 
  148.             } 
  149.  
  150.             break; 
  151.  
  152.         case 'custom-background' : 
  153.             if ( ! is_array( $args ) ) 
  154.                 $args = array( 0 => array() ); 
  155.  
  156.             $defaults = array( 
  157.                 'default-image' => '',  
  158.                 'default-preset' => 'default',  
  159.                 'default-position-x' => 'left',  
  160.                 'default-position-y' => 'top',  
  161.                 'default-size' => 'auto',  
  162.                 'default-repeat' => 'repeat',  
  163.                 'default-attachment' => 'scroll',  
  164.                 'default-color' => '',  
  165.                 'wp-head-callback' => '_custom_background_cb',  
  166.                 'admin-head-callback' => '',  
  167.                 'admin-preview-callback' => '',  
  168.  ); 
  169.  
  170.             $jit = isset( $args[0]['__jit'] ); 
  171.             unset( $args[0]['__jit'] ); 
  172.  
  173.             // Merge in data from previous add_theme_support() calls. The first value registered wins. 
  174.             if ( isset( $_wp_theme_features['custom-background'] ) ) 
  175.                 $args[0] = wp_parse_args( $_wp_theme_features['custom-background'][0], $args[0] ); 
  176.  
  177.             if ( $jit ) 
  178.                 $args[0] = wp_parse_args( $args[0], $defaults ); 
  179.  
  180.             if ( defined( 'BACKGROUND_COLOR' ) ) 
  181.                 $args[0]['default-color'] = BACKGROUND_COLOR; 
  182.             elseif ( isset( $args[0]['default-color'] ) || $jit ) 
  183.                 define( 'BACKGROUND_COLOR', $args[0]['default-color'] ); 
  184.  
  185.             if ( defined( 'BACKGROUND_IMAGE' ) ) 
  186.                 $args[0]['default-image'] = BACKGROUND_IMAGE; 
  187.             elseif ( isset( $args[0]['default-image'] ) || $jit ) 
  188.                 define( 'BACKGROUND_IMAGE', $args[0]['default-image'] ); 
  189.  
  190.             break; 
  191.  
  192.         // Ensure that 'title-tag' is accessible in the admin. 
  193.         case 'title-tag' : 
  194.             // Can be called in functions.php but must happen before wp_loaded, i.e. not in header.php. 
  195.             if ( did_action( 'wp_loaded' ) ) { 
  196.                 /** translators: 1: Theme support 2: hook name */ 
  197.                 _doing_it_wrong( "add_theme_support( 'title-tag' )", sprintf( __( 'Theme support for %1$s should be registered before the %2$s hook.' ),  
  198.                     '<code>title-tag</code>', '<code>wp_loaded</code>' ), '4.1.0' ); 
  199.  
  200.                 return false; 
  201.             } 
  202.     } 
  203.  
  204.     $_wp_theme_features[ $feature ] = $args; 
  205. }