Skip to:
Content
Pages
Categories
Search
Top
Bottom

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.

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.

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.php
  2. 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.