This article explains the difference between WordPress’
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.
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:
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
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
index.php also exist.
front-page.php is not found, then WordPress will use
home.php if it exists. And if neither
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”:
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:
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:
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
Now you see the reason why it is necessary to write a 500 word essay on the difference between
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.phpexists, WordPress will use it to display the contents of the front page.
- Regardless of settings, if neither
home.phpexist, WordPress will use
index.phpto display the front page.
- If the setting “Front page displays” is set to “Your latest posts” and
front-page.phpdoes 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.phpdoes not exist.
- If the setting “Front page displays” is set to “Static page: Posts page”, WordPress will use
home.phpto display blog posts at the URL of the selected Page. And if
home.phpdoesn’t exist, WordPress will use
index.phpto 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: