How to Add Taxonomy Images in WordPress

Adding images to your WordPress categories, tags, or custom taxonomies makes your archive pages visually engaging and helps visitors navigate your content. This guide shows you how to attach images to taxonomy terms without a plugin, and how to display them on your site. You’ll need WordPress admin access and a basic understanding of editing theme files (or a child theme).

What You’ll Need

WordPress admin access (at least Editor or Administrator role).
FTP or file manager access to your theme files (for code snippets).
A child theme (strongly recommended) so your changes aren’t lost on theme updates.
Images you want to use, ideally in a consistent size (e.g., 300×300px).

Step-by-Step

Back up your site – Before editing any files, create a full backup of your WordPress files and database. This protects you if something goes wrong.
Prepare a child theme – If you don’t have one, create a child theme or install a child theme plugin. This ensures your code changes survive theme updates.

Add the image field to taxonomy terms – The easiest way is to add a custom field to each term. Add the following code to your child theme’s functions.php file. This example adds an image upload field to categories and tags:

// Add image field to taxonomy terms
add_action( 'category_add_form_fields', 'add_taxonomy_image_field' );
add_action( 'category_edit_form_fields', 'edit_taxonomy_image_field' );
add_action( 'post_tag_add_form_fields', 'add_taxonomy_image_field' );
add_action( 'post_tag_edit_form_fields', 'edit_taxonomy_image_field' );

function add_taxonomy_image_field( $taxonomy ) {
    ?>
    <div class="form-field">
        <label for="taxonomy-image">Image</label>
        <input type="text" name="taxonomy_image" id="taxonomy-image" value="" />
        <button class="button" id="upload-taxonomy-image">Upload Image</button>
    </div>
    <?php
}

function edit_taxonomy_image_field( $term ) {
    $image = get_term_meta( $term->term_id, 'taxonomy_image', true );
    ?>
    <tr class="form-field">
        <th scope="row"><label for="taxonomy-image">Image</label></th>
        <td>
            <input type="text" name="taxonomy_image" id="taxonomy-image" value="<?php echo esc_attr( $image ); ?>" />
            <button class="button" id="upload-taxonomy-image">Upload Image</button>
        </td>
    </tr>
    <?php
}

// Save the image URL
add_action( 'created_category', 'save_taxonomy_image' );
add_action( 'edited_category', 'save_taxonomy_image' );
add_action( 'created_post_tag', 'save_taxonomy_image' );
add_action( 'edited_post_tag', 'save_taxonomy_image' );

function save_taxonomy_image( $term_id ) {
    if ( isset( $_POST['taxonomy_image'] ) ) {
        update_term_meta( $term_id, 'taxonomy_image', esc_url_raw( $_POST['taxonomy_image'] ) );
    }
}

// Add upload script
add_action( 'admin_enqueue_scripts', 'load_taxonomy_image_script' );
function load_taxonomy_image_script( $hook ) {
    if ( 'edit-tags.php' !== $hook ) return;
    wp_enqueue_media();
    ?>
    <script>
    jQuery(document).ready(function($) {
        $('#upload-taxonomy-image').click(function(e) {
            e.preventDefault();
            var frame = wp.media({ title: 'Select Taxonomy Image', multiple: false });
            frame.on('select', function() {
                var attachment = frame.state().get('selection').first().toJSON();
                $('#taxonomy-image').val(attachment.url);
            });
            frame.open();
        });
    });
    </script>
    <?php
}

Save and test the field – Go to Posts → Categories or Posts → Tags. You should see an “Image” field on the add and edit screens. Upload an image for a term and save it.
Display the image on your site – Now you need to show the image on taxonomy archive pages. Add this code to your child theme’s functions.php or directly to your archive template (e.g., category.php or tag.php):
```
// Get the current term
$term = get_queried_object();
if ( $term && ! is_wp_error( $term ) ) {
    $image = get_term_meta( $term->term_id, 'taxonomy_image', true );
    if ( $image ) {
        echo '<img src="' . esc_url( $image ) . '" alt="' . esc_attr( $term->name ) . '" />';
    }
}
```
Place this where you want the image to appear, typically near the top of the page.

Display images in the term list (optional) – If you want to show images on a page that lists all terms (like a category list), use a custom walker or a shortcode. A simple shortcode example:

add_shortcode( 'taxonomy_image_list', 'taxonomy_image_list_shortcode' );
function taxonomy_image_list_shortcode( $atts ) {
    $atts = shortcode_atts( array( 'taxonomy' => 'category' ), $atts );
    $terms = get_terms( array( 'taxonomy' => $atts['taxonomy'], 'hide_empty' => false ) );
    $output = '<div class="taxonomy-image-list">';
    foreach ( $terms as $term ) {
        $image = get_term_meta( $term->term_id, 'taxonomy_image', true );
        if ( $image ) {
            $output .= '<a href="' . get_term_link( $term ) . '"><img src="' . esc_url( $image ) . '" alt="' . esc_attr( $term->name ) . '" /></a>';
        }
    }
    $output .= '</div>';
    return $output;
}

Then use [taxonomy_image_list taxonomy="category"] in any page.

Common Mistakes

Editing the parent theme directly – Changes are lost when the theme updates. Always use a child theme.
Not escaping output – Echoing the image URL without esc_url() can break your page or introduce security issues.
Using the wrong hook – For custom taxonomies, you need to add actions for that specific taxonomy, not just category and tag.
Forgetting to include the media uploader script – Without wp_enqueue_media(), the upload button won’t work.

Tips

Use a consistent image size – Crop or resize images before uploading to avoid layout shifts.
Consider a plugin for simplicity – If you prefer not to code, plugins like “Taxonomy Images” or “Categories Images” provide the same functionality with a UI.
Cache the term meta – If you have many terms, use wp_cache_get or object caching to speed up queries.
Add a fallback – Use a default placeholder image when no image is set, so the layout doesn’t break.

Troubleshooting

The image field doesn’t appear – Check that you’ve added the code to the correct functions.php (child theme) and that the taxonomy is ‘category’ or ‘post_tag’. For custom taxonomies, replace the hooks accordingly.
The upload button doesn’t work – Ensure you’ve enqueued the media library script. Also check for JavaScript errors in the browser console.
The image isn’t saved – Verify that the form field name matches the one in the save function. Also check that your theme doesn’t strip custom fields.
The image doesn’t display – Confirm the URL is stored correctly in the database (look in wp_termmeta). Also make sure your template code is placed inside the loop or after get_queried_object().

Frequently Asked Questions

Can I add images to custom taxonomies?

Yes, you need to replace ‘category’ and ‘post_tag’ in the hooks with your custom taxonomy slug. For example, if your taxonomy is ‘genre’, use add_action( 'genre_add_form_fields', ... ) and so on.

Will this work with any theme?

The code is theme-independent, but the display part depends on your template. You may need to adjust the template code to match your theme’s HTML structure.

Can I use a plugin instead?

Yes, several plugins provide taxonomy image support with a user-friendly interface. They often offer additional features like image sizes and shortcodes.

How do I remove an image?

Simply clear the image URL field and save the term. The meta data will be updated to an empty string.

Will the image appear in RSS feeds?

No, the image is only displayed where you add the template code. RSS feeds won’t include it unless you add a custom filter.

Does this affect performance?

Storing a URL per term is lightweight. However, if you have thousands of terms, consider caching the term meta to avoid extra database queries.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →