If you’ve done some WordPress theme development, you’ve probably asked yourself these questions: What is the difference between
home.php? When should I use each file?
Home is where the blog is
Because of its blogging heritage, WordPress considers your “home” page to be your blog index page. In other words, it is the list of your latest posts. The concept of the “front page” was added later, to be used when you need your website home to be a static page instead of a list of blog posts. The difference may be subtle, but it can have a big impact on the rest of your theme.
Establishing the hierarchy
To get a better picture of the difference between the two files, let’s take a quick look at the WordPress template hierarchy:
As you follow file specificity from left to right (more specific on the left), note that
front-page.php has higher precedence over
home.php. In fact,
front-page.php has precedence over pretty much everything else, and WordPress will render
front-page.php as the home page, even if you changes the settings in the admin area.
When should I use either file?
Let’s look at how WordPress determines the front page of your site. Log into your admin area and click on Settings > Reading.
Front page is set to blog post index
WordPress sets your front page to show your latest posts by default:
In this case, your front page should show your latest blog posts, and you should use
home.php. If you don’t have either
front-page.php, WordPress will fall back to
Front page is set to a static page
You can, however, set your front page to show a static page. This can be any page you have created in the admin area. Here, I just created a page named “Home” and set it as my front page.
In this case, use
front-page.php. If you don’t have
front-page.php, WordPress will fall back using the Page display rules. Notice in the screenshot I hadn’t selected a page for the Posts page. If you did select a page for that, WordPress will use
home.php to display your latest posts. This is a useful way to move your blog post index to a url slug of your choosing, such as
Why does it matter?
Understanding how to use these two files correctly will help you avoid the following issues:
Don’t use home.php for a static home page, use front-page.php instead
I’ve seen these used in some themes, and some older Genesis child themes employ this method. These themes use
home.php to create static home pages that do not contain blog posts, presumably because this can be done without the users setting anything in the admin area. However, with this approach you won’t have a page template for your blog index. A common workaround for that is to create a custom page template that lists blog posts, create an empty page and set it to that page template. These kinds of page template often use a custom loop, which creates several problems:
- Plugins that are designed to work with the main WordPress loop will not work
- Pagination is much trickier with custom loops, though not impossible
- It causes confusion in the Reading Settings; if the user sets the Front page as a static page, things go haywire
Now that you understand the difference between
front-page.php, the purpose of
is_front_page() becomes clearer, despite the unfortunate naming scheme. If you want to check for the site front page, whether it’s set as the default or a static page, use
is_home() to check for the blog index page. Note that
is_front_page() sometimes check for the same thing, but we can’t always assume that they are.
As if the template naming scheme wasn’t confusing enough, the class that WordPress adds to the
<body> tag for the front page — regardless of the template you are using — is
home. The class that gets added to the blog post index page is
blog. Thankfully, you can differentiate between instances when the home page is set to a static page vs the default:
- When the front page is set to the blog post index, its body classes are
- When the front page is set to a static page, its body classes are
- When the blog post index is set to a static page, its body classes are