Skip to:
Content
Pages
Categories
Search
Top
Bottom
Codex Home → BuddyPress Theme Development → Theme Compatibility → Template Hierarchy

Template Hierarchy

A detailed look at theme compatibilities template hierarchy

BuddyPress 1.7 introduced universal theme compatibility making it easier for WordPress theme designers to work with BuddyPress.

What this means is if you are on a BuddyPress page, BuddyPress will look for a specific template file in your theme and use that template to inject its contents into.

If you’re unfamiliar with BP’s Theme Compatibility please read this guide first which explains the templates and how and where to overload them theme compatibility

The base templates that BP looks for in order of priority are:

Most of the time BP will use page.php since that template file exists in the majority of WordPress themes. However, if you wanted to style BuddyPress pages differently than a regular WordPress page, you could add a template file named buddypress.php to your theme’s directory and BP would use that template instead since that file is ahead of page.php in the hierarchy above.

See also: a-quick-look-at-1-7-theme-compatibility for an introduction to theme compatibility and how to overload the templates to your child theme

This is all fine and dandy if you wanted all your BuddyPress pages to look the same, but let’s say I wanted to style the member pages differently than group pages? You’ll notice that this isn’t quite possible.

What if BuddyPress had a more advanced template hierarchy that looked for additional template files depending on the BuddyPress page you’re on?

BuddyPress 1.8 solves this problem.

Overview of Template Hierarchy in BuddyPress

Single Member Pages

If you are on a single member page, BuddyPress will use the following template hierarchy:

(We will use the following URL as an example – example.com/members/admin/activity/mentions/)

  1. /buddypress/members/single/index-id-{id}.php – If the member profile’s user ID is 1, BuddyPress will look to use /buddypress/members/single/index-id-1.php first.
  2. /buddypress/members/single/index-nicename-{nicename}.php – If we look at the sample URL, the user’s nicename is admin, BuddyPress will look to use /buddypress/members/single/index-nicename-admin.php second.
  3. /buddypress/members/single/index-action-{action}.php – If we look at the sample URL, the action is mentions, BuddyPress will look to use /buddypress/members/single/index-action-mentions.php third.
  4. /buddypress/members/single/index-component-{component}.php – If we look at the sample URL, the component is activity, BuddyPress will look to use /buddypress/members/single/index-component-activity.php fourth.
  5. /buddypress/members/single/index.php – If this template file is used in your theme, all member pages will use this template. BP will look to use this if the other four templates mentioned above are not found.
  6. The rest of the base templates as listed here.

Single Member Front page

Since version 2.6.0, if a front.php template is located into the /buddypress/members/single/ directory it will be used as the home page for members profile pages. This template is not included into the BP Legacy template pack. Themes can use it to customize the Member’s home page. If you need different front pages for your users, you can use this template hierarchy:

  1. /buddypress/members/single/front-id-{id}.php – If the member’s ID is 42, BuddyPress will look to use /buddypress/members/single/front-id-42.php first.
  2. /buddypress/members/single/front-nicename-{nicename}.php – If the member’s nicename is “john”, BuddyPress will look to use /buddypress/members/single/front-nicename-john.php second.
  3. /buddypress/members/single/front-member-type-{member-type}.php – If you registered member types (see this codex page), you can use the member type name to build different front pages for each member type. For instance BP will look to use /buddypress/members/single/front-member-type-student.php if the other two templates mentioned above are not found and the displayed user has the “student” member type.
  4. /buddypress/members/single/front.php – If none of the above are found.

If you have trouble determining the action or component, you could try using this small debug plugin to help output information about the current BuddyPress page.

Single Group Pages

If you are on a single group page, BuddyPress will use the following template hierarchy:

(We will use the following URL as an example – example.com/groups/my-test-group/members/)

  1. /buddypress/groups/single/index-id-{id}.php -If the group’s ID is 1, BuddyPress will look to use /buddypress/groups/single/index-id-1.php first.
  2. /buddypress/groups/single/index-slug-{slug}.php – If we look at the sample URL, the slug is my-test-group, BuddyPress will look to use /buddypress/groups/single/index-slug-my-test-group.php second.
  3. /buddypress/groups/single/index-action-{action}.php – If we look at the sample URL, the action is members, BuddyPress will look to use /buddypress/groups/single/index-action-members.php third.
  4. /buddypress/groups/single/index-status-{status}.php – Either public, private or hidden. So let’s say you wanted all private groups to have a similar look, you would want to add the following template – /buddypress/groups/single/index-status-private.php. BP will look to use this if the other three templates mentioned above are not found.
  5. /buddypress/groups/single/index.php – If this template file is used in your theme, all group pages will use this template. BP will look to use this if the other three templates mentioned above are not found.
  6. The rest of the base templates as listed here.

Single Groups Front page

Since version 2.4.0, we added a template hierarchy to the front.php template. This template is not included into the BP Legacy template pack. Themes can use it to customize the Group’s home page.

  1. /buddypress/groups/single/front-id-{id}.php – If the group’s ID is 1, BuddyPress will look to use /buddypress/groups/single/front-id-1.php first.
  2. /buddypress/groups/single/front-slug-{slug}.php – If we look at the sample URL, the slug is my-test-group, BuddyPress will look to use /buddypress/groups/single/front-slug-my-test-group.php second.
  3. /buddypress/groups/single/front-group-type-{type}.php – (Since 2.6.0) If the group has the type of “team”, BuddyPress will look to use /buddypress/groups/single/front-group-type-team.php next.
  4. /buddypress/groups/single/front-status-{status}.php – Either public, private or hidden. So let’s say you wanted all public groups to have a similar front page, you would want to add the following template – /buddypress/groups/single/front-status-public.php. BP will look to use this if the templates mentioned above are not found.
  5. /buddypress/groups/single/front.php – If none of the above are found.

If you have trouble determining the slug, action or status, you could try using this small debug plugin to help output information about the current BuddyPress page.

If you are on an activity permalink page, BuddyPress will use the following template hierarchy:

  1. /buddypress/activity/single/index.php
  2. The rest of the base templates as listed here.

Activity Directory page

If you are on the activity directory page, BuddyPress will use the following template hierarchy:

  1. /buddypress/activity/index-directory.php
  2. The rest of the base templates as listed here.

Member Directory page

If you are on the members directory page, BuddyPress will use the following template hierarchy:

  1. /buddypress/members/index-directory-type-{member_type}.php when viewing member type specific directory page, {member_type} is the current member type.
  2. /buddypress/members/index-directory.php
  3. The rest of the base templates as listed here.

Group Directory page

If you are on the groups directory page, BuddyPress will use the following template hierarchy:

  1. /buddypress/groups/index-directory.php
  2. The rest of the base templates as listed here.

Group Creation page

If you are on the group creation page, BuddyPress will use the following template hierarchy:

  1. /buddypress/groups/index-create.php
  2. The rest of the base templates as listed here.

Site Directory page

Only applicable if you are running WordPress multisite.

If you are on the site directory page, BuddyPress will use the following template hierarchy:

  1. /buddypress/blogs/index-directory.php
  2. The rest of the base templates as listed here.

Site Creation page

Only applicable if you are running WordPress multisite.

If you are on the site creation page, BuddyPress will use the following template hierarchy:

  1. /buddypress/blogs/index-create.php
  2. The rest of the base templates as listed here.

Registration page

If you are on the registration page, BuddyPress will use the following template hierarchy:

  1. /buddypress/members/index-register.php
  2. The rest of the base templates as listed here.

Activation page

If you are on the activation page, BuddyPress will use the following template hierarchy:

  1. /buddypress/members/index-activate.php
  2. The rest of the base templates as listed here.

Contents

Article Contributors

9
r-a-y
6
Hugo Ashmore
5
Mathieu Viet

Updated 8 years ago / Published 11 years ago

Want to help?

The BuddyPress Codex is volunteer-powered, which means you can contribute too! If you're interested in updating existing articles or creating entirely new ones, please read our Codex Standards & Guidelines.

Skip to toolbar