Using WordPress ‘display_media_states’ PHP filter

by

The display_media_states WordPress PHP filter allows you to modify the default media display states for items in the Media list table.

Usage

add_filter('display_media_states', 'your_custom_function', 10, 2);

function your_custom_function($media_states, $post) {
    // your custom code here

    return $media_states;
}

Parameters

  • $media_states (string[]): An array of media states. Default ‘Header Image’, ‘Background Image’, ‘Site Icon’, ‘Logo’.
  • $post (WP_Post): The current attachment object.

More information

See WordPress Developer Resources: display_media_states

Examples

Add a new media state called “Featured Image” when an image is used as a featured image.

add_filter('display_media_states', 'add_featured_image_state', 10, 2);

function add_featured_image_state($media_states, $post) {
    if (has_post_thumbnail() && get_post_thumbnail_id() == $post->ID) {
        $media_states[] = 'Featured Image';
    }
    return $media_states;
}

Remove “Background Image” state

Remove the “Background Image” state from the Media list table.

add_filter('display_media_states', 'remove_background_image_state', 10, 2);

function remove_background_image_state($media_states, $post) {
    $key = array_search('Background Image', $media_states);
    if ($key !== false) {
        unset($media_states[$key]);
    }
    return $media_states;
}

Replace “Site Icon” state with custom text

Replace the “Site Icon” state with a custom text “Favicon”.

add_filter('display_media_states', 'replace_site_icon_state', 10, 2);

function replace_site_icon_state($media_states, $post) {
    $key = array_search('Site Icon', $media_states);
    if ($key !== false) {
        $media_states[$key] = 'Favicon';
    }
    return $media_states;
}

Add a custom media state for specific file types

Add a custom media state “Video Thumbnail” for JPEG images that are attached to video posts.

add_filter('display_media_states', 'add_video_thumbnail_state', 10, 2);

function add_video_thumbnail_state($media_states, $post) {
    if ($post->post_mime_type == 'image/jpeg' && get_post_type($post->post_parent) == 'video') {
        $media_states[] = 'Video Thumbnail';
    }
    return $media_states;
}

Add a custom media state for a specific user

Add a custom media state “User’s Favorite” for media uploaded by a specific user.

add_filter('display_media_states', 'add_users_favorite_state', 10, 2);

function add_users_favorite_state($media_states, $post) {
    $favorite_user_id = 5; // Change this to the specific user ID
    if ($post->post_author == $favorite_user_id) {
        $media_states[] = "User's Favorite";
    }
    return $media_states;
}