WP-Mix

This article explains the difference between WordPress’ home.php and front-page.php theme templates, as related to the display of your site’s front page. For best results, log in to the Admin Area of your WP installation and follow along with the text.

Purpose

The purpose of this post is to clear up any confusion with the various theme template files that WordPress may use to display the front page (aka home page). Specifically, we’re focusing on the following template files:

• front-page.php
• home.php
• index.php

Depending on configuration, one of these templates will be used to display the front page. To determine which file will be used, we must look at WordPress’ Front-page setting. This setting is located in the WP Admin Area in the following location:

Dashboard > Settings > Reading > Front page displays

There are two options available for the “Front page displays” setting:

• Your latest posts
• A static page

So depending on the option selected here, WordPress will use either front-page.php, home.php, index.php, or some other file to display the front page. Here’s how it works..

Front page setting = Your latest posts

When the “Front page displays” setting is set to “Your latest posts”, WordPress first checks for the front-page.php template. If front-page.php exists, it will be used to display your latest posts on the front page, regardless of whether or not home.php or index.php also exist.

If front-page.php is not found, then WordPress will use home.php if it exists. And if neither front-page.php nor home.php exist, then WordPress will use the index.php file to display your latest posts.

Thus, here is the order in which WordPress uses these template files when the Front-page setting is set to show “Your latest posts”:

front-page.php → home.php → index.php

So far, so good.

Front page setting = A static page

Here is where things get tricky. When you select “A static page” for the Front-page setting, two sub-options become available:

• Front page (select from existing Pages)
• Posts page (select from existing Pages)

Note: at least one of these sub-options must be specified in order for the “A static page” option to remain active. That is, if you select “A static page” but do not specify either a “Front page” or a “Posts page”, WordPress automatically will revert the setting back to “Your latest posts”.

Now let’s examine each of these “static page” settings..

Front page setting = A static page: Front page

When the “Front page” sub-option specifies which Page to use as the static front page, WordPress first checks for front-page.php. If it exists, WordPress will use it to display the content of the specified Page as the front page. If front-page.php does not exist, WordPress checks for the following files, in order, to determine which template to use:

front-page.php → page-custom.php → page.php → index.php

That’s a bit abstract, so let’s look at a real-word example. Let’s say that you have selected your “About” Page for the setting, Front page displays > A static page > Front page. Click here for screenshot. In this scenario, WordPress checks for the following template files and uses the first one it finds to display the contents of the About page:

front-page.php → page-about.php → page.php → index.php

Note: instead of using a file named page-about.php, WordPress may use any page template that is specified in the “Page Attributes” panel on the “Edit Page” screen. Click here for screenshot.

The important thing to keep in mind for the setting, “A static page: Front page”, is that WordPress displays the contents of the selected Page using whichever template file is discovered first in the hierarchy. This allows for maximum flexibility.

Also note that, in this scenario, when the Front-page setting is set to “A static page”, the home.php template is not used for anything.

Front page setting = A static page: Posts page

The other setting for Static page, “Posts page”, does something entirely different. Instead of determining what is shown of the site’s front page (aka homepage), this setting determines which Page should be used to display the blog’s posts. That is, if this setting is enabled, the selected Page will be used to display blog posts.

Thus, the setting, “A static page: Posts page”, enables you to specify a location to display your blog posts. This can be useful if you also have enabled a custom Page for the front page via the setting, “A static page: Front page”. So you can customize the front page to display some static content, and then display your blog posts at the URL of the selected posts page.

It’s important to understand that this setting does not display content on the front page, but rather displays blog posts on the selected page. And the blog posts are displayed using the index.php template, which overrides any custom page template that may be in place. The only theme template that can override the index.php in this case is home.php, as you can visualize using the table provided in the next section.

Here is the template hierarchy for the setting, “A static page: Posts page”:

home.php -> index.php

Summary

Now you see the reason why it is necessary to write a 500 word essay on the difference between front-page.php and home.php: it can be very confusing depending on how your site is configured. If you’re still scratching your head wondering what’s up, here is a concise summary that should make it all clear:

• Regardless of any settings, if front-page.php exists, WordPress will use it to display the contents of the front page.
• Regardless of settings, if neither front-page.php nor home.php exist, WordPress will use index.php to display the front page.
• If the setting “Front page displays” is set to “Your latest posts” and front-page.php does not exist, WordPress will use home.php (if it exists).
• If the setting “Front page displays” is set to “Static page: Front page”, WordPress will use the selected Page if front-page.php does not exist.
• If the setting “Front page displays” is set to “Static page: Posts page”, WordPress will use home.php to display blog posts at the URL of the selected Page. And if home.php doesn’t exist, WordPress will use index.php to display blog posts at the URL of the selected Page.

Here is the same information presented via table:

Front page displays     Hierarchy
===================     =========

Your latest posts       -> front-page.php -> home.php -> index.php

Static page: Front page -> front-page.php -> page-custom.php -> page.php -> index.php

Static page: Posts page -> home.php -> index.php

To put this information in context, examine the WordPress Template Hierarchy:

https://developer.wordpress.org/files/2014/10/template-hierarchy.png