Wordpress - Template Hierarchy: confused with index.php, front-page.php, home.php

Front page logic is one of the most confusing features in WordPress and is exceptionally hard to explain and summarize. As mentioned in comment while back I burnt unholy amount of time to put together my front page logic cheat sheet for it.

But since this is a popular thread let me try to answer those very specific questions you had.

What's the difference between the home.php and index.php?

home.php is template for posts index (archive of native Post post type, which is a special case in WP). WP will attempt to look it up for index of posts, whether they are displayed at the root of the site or at dedicated posts page.

index.php is catch–all template. It is final choices in all branches of template hierarchy and will be picked when nothing else fits, for both archives and singular views.

Only posts index can use home.php, but all other contexts might and will use index.php.

What's the ideal condition to use a home.php than an index.php

You use home.php to customize posts index.

You use index.php to provide the most generic template in your theme, suitable for display of anything.

Some themes choose to have empty index.php and ensure they have more specific templates for all possible cases, so it never has to be used.

What's the ideal condition to use a front-page.php?

front-page.php is used for posts index at the root or static front page, if enabled.

It is a high priority template, so if theme has it you cannot select arbitrary template for static front page. For this reason it is almost never included in publicly released themes (which is correct).

The best use for it is in private projects, since it's easier to configure than page template.

When I'm using a front-page.php then what specific task an index.php is doing for me then?

index.php is still a catch all template for all other cases.

If you use static front page (to which front-page.php will apply) then your posts page will try to use home.php and then index.php.


The front-page.php file is the site front page template. It will always be used on your site front page, regardless of whether get_option( 'show_on_front' ) is set to page or posts.

The home.php template file is the blog posts index template. It will always be used to display your blog posts index, regardless of whether the blog posts index is displayed on the site front page, or on a different page.

In the case that both front-page.php and home.hpp exist, and the get_option( 'show_on_front' ) is set to posts (i.e., the site front page displays the blog posts index), the front-page.php file will take precedence over the home.php file.

The index.php file is the default fallback template for all contexts in the Template Hierarchy. It is only ever used if a more-specific template file does not exist for the current context.

The template hierarchy for the site front page is:

  • front-page.php
  • If 'page' == get_option( 'show_on_front' ): page hierarchy
  • If 'posts' == get_option( 'show_on_front' ): blog posts index hierarchy

The template hierarchy for the blog posts index is:

  • home.php
  • index.php

The template hierarchy for pages is:

  • Custom page template
  • page-{slug}.php
  • page-{id}.php
  • page.php
  • index.php

All this comes from a thorough reading of the Template Hierarchy.

home.php is used if:

  • Your site's front page is set to display a list of posts, or
    • A static front page is set, and
    • A visitor goes to the page that you've defined as your "list of posts" (eg, http://example.com/blog/)
  • And the theme has a home.php file

If the last condition isn't met -- ie, there is no home.php file in the theme -- then index.php will be loaded.

front-page.php will be used if:

  • A static front page is set, and
  • A visitor goes to the page that you've defined as your "static home page" (ie, http://example.com/), and
  • The theme has a front-page.php file

If the last condition isn't met -- ie, there is no front-page.php file in the theme -- then index.php will be loaded.

In summary

If you want to customize your list of posts, use home.php.
If you want to customize your static home page, use front-page.php.

Tags:

Template Hierarchy

Recent Posts