Using WordPress ‘register_default_headers()’ PHP function

by

The register_default_headers() WordPress PHP function registers a selection of default headers to be displayed by the custom header admin UI.

Usage

register_default_headers(array(
    'header1' => array(
        'url' => '%s/images/headers/header1.jpg',
        'thumbnail_url' => '%s/images/headers/header1-thumbnail.jpg',
        'description' => __('Header 1', 'yourtheme')
    )
));

Parameters

  • $headers (array) – Required. Array of headers keyed by a string ID. The IDs point to arrays containing ‘url’, ‘thumbnail_url’, and ‘description’ keys.

More information

See WordPress Developer Resources: register_default_headers()

Examples

Registering multiple default headers

Register multiple default headers for your theme.

register_default_headers(array(
    'forest' => array(
        'url' => '%s/images/headers/forest.jpg',
        'thumbnail_url' => '%s/images/headers/forest-thumbnail.jpg',
        'description' => __('Forest', 'yourtheme')
    ),
    'mountains' => array(
        'url' => '%s/images/headers/mountains.jpg',
        'thumbnail_url' => '%s/images/headers/mountains-thumbnail.jpg',
        'description' => __('Mountains', 'yourtheme')
    ),
    'city' => array(
        'url' => '%s/images/headers/city.jpg',
        'thumbnail_url' => '%s/images/headers/city-thumbnail.jpg',
        'description' => __('City', 'yourtheme')
    )
));

Using child theme images

Register a default header for your child theme.

register_default_headers(array(
    'child_theme_header' => array(
        'url' => '%2$s/images/headers/child_theme_header.jpg',
        'thumbnail_url' => '%2$s/images/headers/child_theme_header-thumbnail.jpg',
        'description' => __('Child Theme Header', 'yourtheme')
    )
));

Localization of header descriptions

Localize header descriptions for translation.

register_default_headers(array(
    'beach' => array(
        'url' => '%s/images/headers/beach.jpg',
        'thumbnail_url' => '%s/images/headers/beach-thumbnail.jpg',
        'description' => __('Beach', 'yourtheme')
    ),
    'sky' => array(
        'url' => '%s/images/headers/sky.jpg',
        'thumbnail_url' => '%s/images/headers/sky-thumbnail.jpg',
        'description' => __('Sky', 'yourtheme')
    )
));

Registering a single default header

Register a single default header for your theme.

register_default_headers(array(
    'ocean' => array(
        'url' => '%s/images/headers/ocean.jpg',
        'thumbnail_url' => '%s/images/headers/ocean-thumbnail.jpg',
        'description' => __('Ocean', 'yourtheme')
    )
));

Using different image formats

Register default headers with different image formats, such as PNG or GIF.

register_default_headers(array(
    'header_png' => array(
        'url' => '%s/images/headers/header_png.png',
        'thumbnail_url' => '%s/images/headers/header_png-thumbnail.png',
        'description' => __('Header PNG', 'yourtheme')
    ),
    'header_gif' => array(
        'url' => '%s/images/headers/header_gif