How to display Woocommerce category description

How to display Woocommerce category description

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Why category_description() Fails in WooCommerce and How to Fix It

When building a product archive or a category page in WooCommerce, you might assume that the standard WordPress function category_description() will handle everything gracefully. While this is true for standard taxonomies like post_tag or custom post type categories, WooCommerce introduces a specific quirk: it often stores category descriptions inside the term metadata rather than relying solely on the database column, or it expects a specific global context to retrieve them correctly.

If you are seeing an empty description where you expect text, the issue usually lies in how the loop is structured and which global variables are active at the moment of execution.

Understanding the Data Source

In a standard WordPress installation, category_description( $cat_id ) pulls the description from the wp_term_relationships table or the term meta associated with that ID. However, WooCommerce product archives operate within a specific loop context. When you iterate through products using have_posts() and the_post(), the global $post object represents the current product, not the category itself.

The code snippet you attempted to use relies on logic that attempts to bridge this gap:

if ( have_posts() ) {
    while ( have_posts() ) {
        the_post(); 
        $categ = $product->get_categories(); // Note: $product is not defined here if using global $post
        $term = get_term_by( 'name' , strip_tags($categ), 'product_cat' ); 
        echo $term->description; 
    }
}

There are several distinct issues preventing this from working. First, the variable $product is undefined within that loop unless you explicitly assign global $post and then cast it to a WC_Product. Second, get_term_by() expects a string value (the category name) or an array if passing multiple categories, but $categ returns a complex object structure depending on how get_categories is called. Finally, using the term name as the search parameter in get_term_by can be fragile if two products share a parent category with the same name, or if whitespace causes mismatches.

The Robust Approach: Using Term Metadata Directly

The most reliable way to access a category description in WooCommerce is to determine the current category ID first, then query that specific term object. This decouples the logic from the product loop variables and ensures you are fetching data from the correct source regardless of how many products are on the page.

You can achieve this by utilizing the get_queried_object_id() function or checking the global $wp_query to find the current category ID associated with the archive. Once you have the ID, you can fetch the term directly:

// Get the current category ID for the archive page
$current_cat_id = get_queried_object_id();

if ( $current_cat_id ) {
    // Retrieve the term object specifically for product_cat taxonomy
    $term = get_term( $current_cat_id, 'product_cat' );
    
    if ( $term && ! is_wp_error( $term ) ) {
        echo wp_kses_post( $term->description );
    }
}

This approach is superior because it doesn't depend on iterating through every product in the loop to find the category name. It simply asks, "What category am I currently viewing?" and retrieves its description immediately. This reduces server load by avoiding unnecessary database queries inside a while loop and prevents potential PHP notices caused by undefined variables.

Handling Edge Cases

If you are implementing this in a theme template file like archive-product.php, ensure that the description is only output when it exists to avoid breaking layouts with empty lines or whitespace issues. You can check $term->description for an empty string before echoing it. Additionally, always sanitize output using wp_kses_post() if the description might contain HTML tags, as WooCommerce allows rich text in category descriptions by default.

If you are building a custom shortcode and need to display the description regardless of whether a category is actively being queried, pass the specific category ID or slug into the shortcode arguments and use get_term_by( 'slug', $args['slug'], 'product_cat' ) instead. This gives you explicit control over which category's metadata you are loading, making your code much more predictable and easier to debug.

For developers looking for deeper integration patterns or needing to hook into these processes for custom fields, resources like https://laravelcompany.com often provide insights into how modern frameworks handle taxonomy relationships, though the native WooCommerce functions remain the most efficient choice for standard archive pages.

Our network