How to Add and Upload Category Images in WordPress Easily

Upload Category Images By default, WordPress categories don’t support images. This can be a problem if you want to make your blog archives, sliders, or category grids look more attractive.

In this tutorial, we’ll show you how to:

Add a category image upload option in WordPress.
Save category images using term meta.
Display category images on the frontend.

Whether you’re building a blog, magazine site, or WooCommerce shop, this will help you create visually engaging category layouts.

Step 1: Load Media Uploader in WordPress Admin

We first need to load the WordPress Media Uploader so admins can upload/select images when editing categories.

Add this code to your theme’s functions.php or a custom plugin:

// Load media uploader for category pages
function my_category_enqueue_media() {
    if (isset($_GET['taxonomy']) && $_GET['taxonomy'] === 'category') {
        wp_enqueue_media();
        wp_enqueue_script('jquery');
    }
}
add_action('admin_enqueue_scripts', 'my_category_enqueue_media');

Step 2: Add Category Image Field

Now let’s add an image upload field when creating or editing a category.

// Add field on "Add Category"
function my_category_add_field() {
    ?>
    <div class="form-field term-group">
        <label for="category-image">Category Image</label>
        <input type="hidden" id="category-image" name="category-image" value="">
        <div id="category-image-preview"></div>
        <button type="button" class="button category-image-upload">Upload Image</button>
        <button type="button" class="button category-image-remove">Remove Image</button>
    </div>
    <?php
}
add_action('category_add_form_fields', 'my_category_add_field');

And for the edit screen:

// Edit category field
function my_category_edit_field($term) {
    $image_id = get_term_meta($term->term_id, 'category-image', true);
    $image_url = $image_id ? wp_get_attachment_url($image_id) : '';
    ?>
    <tr class="form-field term-group-wrap">
        <th scope="row"><label for="category-image">Category Image</label></th>
        <td>
            <input type="hidden" id="category-image" name="category-image" value="<?php echo esc_attr($image_id); ?>">
            <div id="category-image-preview">
                <?php if ($image_url): ?>
                    <img src="<?php echo esc_url($image_url); ?>" style="max-width:150px;height:auto;">
                <?php endif; ?>
            </div>
            <button type="button" class="button category-image-upload">Upload Image</button>
            <button type="button" class="button category-image-remove">Remove Image</button>
        </td>
    </tr>
    <?php
}
add_action('category_edit_form_fields', 'my_category_edit_field');

Step 3: Save Category Image Meta

When a category is created or updated, we save the selected image into term meta.

function my_category_save_image($term_id) {
    if (isset($_POST['category-image']) && $_POST['category-image'] !== '') {
        update_term_meta($term_id, 'category-image', intval($_POST['category-image']));
    } else {
        delete_term_meta($term_id, 'category-image');
    }
}
add_action('created_category', 'my_category_save_image');
add_action('edited_category', 'my_category_save_image');

Step 4: Add JavaScript for Media Uploader

Finally, add JavaScript so the buttons work properly:

function my_category_image_script() {
    ?>
    <script>
    jQuery(document).ready(function($){
        var mediaUploader;

        function openUploader() {
            mediaUploader = wp.media({
                title: 'Choose Category Image',
                button: { text: 'Use this image' },
                multiple: false
            });

            mediaUploader.on('select', function(){
                var attachment = mediaUploader.state().get('selection').first().toJSON();
                $('#category-image').val(attachment.id);
                $('#category-image-preview').html('<img src="'+attachment.url+'" style="max-width:150px;height:auto;">');
            });

            mediaUploader.open();
        }

        $('.category-image-upload').click(function(e){
            e.preventDefault();
            openUploader();
        });

        $('.category-image-remove').click(function(){
            $('#category-image').val('');
            $('#category-image-preview').html('');
        });
    });
    </script>
    <?php
}
add_action('admin_footer', 'my_category_image_script');

Step 5: Display Category Images on the Frontend

Now that categories have images, we can display them in your theme.

For example, inside category.php or archive.php:

<?php
$category = get_queried_object();
$image_id = get_term_meta($category->term_id, 'category-image', true);

if ($image_id) {
    echo wp_get_attachment_image($image_id, 'medium');
}
?>
<h1><?php single_cat_title(); ?></h1>

Full Code

<?php
// Load Media Uploader Script
function my_category_enqueue_media() {
    if (isset($_GET['taxonomy']) && $_GET['taxonomy'] === 'category') {
        wp_enqueue_media();
        wp_enqueue_script('jquery');
    }
}
add_action('admin_enqueue_scripts', 'my_category_enqueue_media');


// Add field on "Add Category"
function my_category_add_field() {
    ?>
    <div class="form-field term-group">
        <label for="category-image">Category Image</label>
        <input type="hidden" id="category-image" name="category-image" value="">
        <div id="category-image-preview"></div>
        <button type="button" class="button category-image-upload">Upload Image</button>
        <button type="button" class="button category-image-remove">Remove Image</button>
    </div>
    <?php
}
add_action('category_add_form_fields', 'my_category_add_field');


// Add field on "Edit Category"
function my_category_edit_field($term) {
    $image_id = get_term_meta($term->term_id, 'category-image', true);
    $image_url = $image_id ? wp_get_attachment_url($image_id) : '';
    ?>
    <tr class="form-field term-group-wrap">
        <th scope="row"><label for="category-image">Category Image</label></th>
        <td>
            <input type="hidden" id="category-image" name="category-image" value="<?php echo esc_attr($image_id); ?>">
            <div id="category-image-preview">
                <?php if ($image_url): ?>
                    <img src="<?php echo esc_url($image_url); ?>" style="max-width:150px;height:auto;">
                <?php endif; ?>
            </div>
            <button type="button" class="button category-image-upload">Upload Image</button>
            <button type="button" class="button category-image-remove">Remove Image</button>
        </td>
    </tr>
    <?php
}
add_action('category_edit_form_fields', 'my_category_edit_field');


// Save image when category is created/edited
function my_category_save_image($term_id) {
    if (isset($_POST['category-image']) && $_POST['category-image'] !== '') {
        update_term_meta($term_id, 'category-image', intval($_POST['category-image']));
    } else {
        delete_term_meta($term_id, 'category-image');
    }
}
add_action('created_category', 'my_category_save_image');
add_action('edited_category', 'my_category_save_image');

// JS for uploader
function my_category_image_script() {
    ?>
    <script>
    jQuery(document).ready(function($){
        var mediaUploader;

        function openUploader(button) {
            mediaUploader = wp.media({
                title: 'Choose Category Image',
                button: { text: 'Use this image' },
                multiple: false
            });

            mediaUploader.on('select', function(){
                var attachment = mediaUploader.state().get('selection').first().toJSON();
                $('#category-image').val(attachment.id);
                $('#category-image-preview').html('<img src="'+attachment.url+'" style="max-width:150px;height:auto;">');
            });

            mediaUploader.open();
        }

        $('.category-image-upload').click(function(e){
            e.preventDefault();
            openUploader($(this));
        });

        $('.category-image-remove').click(function(){
            $('#category-image').val('');
            $('#category-image-preview').html('');
        });
    });
    </script>
    <?php
}
add_action('admin_footer', 'my_category_image_script');

?>

Conclusion

Adding images to categories in WordPress helps improve user experience and gives your website a more professional look. With just a few lines of code, you can upload category images, save them in the database, and display them anywhere on your site.

This method works for default categories, but you can also adapt it for custom taxonomies (like WooCommerce product categories).