Adding Classes to body_class() in WordPress

Adding Classes to `body_class()` in WordPress

When building or customizing WordPress themes, you often need to add custom CSS classes to the <body> tag for styling or JavaScript targeting. WordPress provides the body_class() function to output classes dynamically, but sometimes you want to add your own classes programmatically. This tutorial explains how to add classes to body_class() in WordPress the right way, with updated code for modern WordPress, including block themes and Gutenberg considerations.

Quick Fix: How to Add Classes to `body_class()`

Open your theme’s functions.php file or create a small plugin.
Add a filter to body_class that appends your custom classes.
Test by viewing your site’s source code and verifying the <body> tag classes.

Why This Happens

The body_class() function outputs an array of CSS classes for the <body> tag, reflecting the current page context (e.g., home, single post, category). By default, WordPress controls these classes, but developers often need to add custom classes for additional styling or scripting purposes. Directly editing theme templates to hardcode classes is not recommended because it breaks flexibility and maintainability. Instead, WordPress provides a filter hook body_class to safely modify or add classes.

When to Use Custom Classes in `body_class()`

Adding page-specific or user-specific CSS hooks.
Targeting custom post types or taxonomies with CSS or JS.
Adding classes based on user roles or login status.
Conditionally styling parts of your theme without modifying templates.

Updated Code for Modern WordPress

Since WordPress 5.0+ and the rise of block themes and Gutenberg, the method to add classes remains the same but you should ensure your code is compatible with block-based templates and full site editing.

Here is the recommended approach using the body_class filter:

function my_custom_body_classes( $classes ) {
    // Add a custom class
    $classes[] = 'my-custom-class';

    // Conditionally add a class on the homepage
    if ( is_front_page() ) {
        $classes[] = 'front-page-class';
    }

    // Add class if user is logged in
    if ( is_user_logged_in() ) {
        $classes[] = 'logged-in-user';
    }

    return $classes;
}
add_filter( 'body_class', 'my_custom_body_classes' );

How to Add Custom Classes via `functions.php` or a Small Plugin

Via functions.php:
Open your active theme’s functions.php file and paste the code snippet above at the end of the file.

Via a small plugin:

Create a new PHP file in wp-content/plugins/ named custom-body-classes.php with the following content:

<?php
    /*
    Plugin Name: Custom Body Classes
    Description: Adds custom classes to the body tag.
    Version: 1.0
    Author: Your Name
    */

    function my_custom_body_classes( $classes ) {
        $classes[] = 'my-custom-class';
        if ( is_front_page() ) {
            $classes[] = 'front-page-class';
        }
        if ( is_user_logged_in() ) {
            $classes[] = 'logged-in-user';
        }
        return $classes;
    }
    add_filter( 'body_class', 'my_custom_body_classes' );

Then activate this plugin from the WordPress admin.

Step-by-Step Test

Add the code snippet to your functions.php or activate the plugin.
Clear any caches if you use caching plugins or server caching.
Visit your homepage and view the page source (right-click > View Page Source).
Locate the <body> tag and verify your custom classes appear, e.g., my-custom-class and front-page-class.
Log in to your WordPress admin and refresh the page to confirm logged-in-user class appears.
Test on other pages to verify classes change according to conditions.

Block Themes & Gutenberg Notes

Block themes and the Full Site Editing (FSE) experience introduced in WordPress 5.9+ do not change how body_class() works. The body_class filter remains the standard way to add classes. However, some block themes may use different templates or wrappers, so ensure your theme calls body_class() in the <body> tag.

For block themes, you can also add classes via the theme.json file or custom block styles, but for global body classes, the filter method is still best.

Common Pitfalls

Not returning the modified classes array: Always return the modified $classes array in your filter function.
Adding classes as a string: The filter expects an array of classes, so add classes by appending to the array, not as a string.
Forgetting to hook the filter: Make sure to add add_filter( 'body_class', 'your_function' );.
Cache issues: Changes might not appear immediately if caching plugins or server caches are active.
Theme compatibility: Some themes may override body_class() or not call it properly; verify your theme outputs it in the <body> tag.

Works On

WordPress Snippets body_class, PHP, Theme, WordPress

Server/Environment	Compatibility
Apache	Fully compatible
Nginx	Fully compatible
LiteSpeed	Fully compatible