BuddyPress

BuddyPress Hooks Cheat Sheet: 50 Essential Actions and Filters

All 50 BuddyPress hooks in this cheat sheet were checked against the 14.5.4 source on 15 November 2026, with the file for each, plus how bp_directory_members_item works and which hooks were deprecated in 12.0.

·10 min read
BuddyPress Hooks Cheat Sheet: 50 actions and filters checked against BuddyPress 14.5.4

The hook people search for most on this page is bp_directory_members_item. It is an action with no arguments. BuddyPress fires it once for every member in the Members directory loop, so you can echo extra markup under each member card, and it exists in both the Nouveau and the legacy template packs. In Nouveau it only runs on the Members directory page and only when something is hooked to it.

This cheat sheet lists 50 actions and filters. We checked every one of them against the BuddyPress 14.5.4 source (released 23 October 2026, the current version on WordPress.org) on 15 November 2026, and each row names the file where the hook fires. We removed hooks from the earlier version of this post that do not exist in the current source, and a table further down shows what to use instead.

People reach this page with queries such as “buddypress bp_directory_members_item hook documentation” and “bp_directory_members_item action”. Those are the questions we answer first. The rest is organised by component so you can jump to the part of BuddyPress you are changing. Our team builds community sites on BuddyPress and on BuddyNext, and these are the hooks we reach for most.

What is bp_directory_members_item?

It is a no-argument action that fires inside each member item of the Members directory loop. Use it to add a line of extra content, such as a job title, a badge or a membership level, beneath every member in the list. BuddyPress documents it as firing inside the display of a directory member item, and it has existed since version 1.1.0.

How it behaves depends on the template pack. In the legacy pack the hook is called directly in members/members-loop.php. In Nouveau, the default pack, the call sits in bp_nouveau_member_extra_content() (file bp-templates/bp-nouveau/includes/members/template-tags.php), and the template only calls that function when bp_nouveau_member_has_extra_content() returns true. That check needs two things: you are on the Members directory, and at least one callback is hooked to the action. A filter named bp_nouveau_member_extra_content_in_members_directory lets you extend the first condition to other pages.

There is a history here. BuddyPress 3.0 put this hook in the wrong place inside the item meta, and BuddyPress 6.0 moved that spot to a new action, bp_directory_members_item_meta, so extra metadata and extra content now have separate hooks. The change is recorded in Trac ticket #8183 (mailing list archive).

Checked on 15 November 2026 against BuddyPress 14.5.4. A small working example:

<?php
// Show the member's last activity under each card in the Members directory.
// Works in Nouveau (BuddyPress 6.0+) and the legacy template pack.
add_action( 'bp_directory_members_item', function () {
	$last_active = bp_get_member_last_active();
	if ( $last_active ) {
		printf(
			'<p class="member-last-seen">%s</p>',
			esc_html( $last_active )
		);
	}
} );

If your callback never runs, work through the likely causes in this order: the theme or a child theme overrides members/members-loop.php and dropped the call, the page is a member list inside a block or shortcode that does not use the directory loop, or your site runs a different community platform that ships its own templates.

How do actions and filters work?

An action lets you run code at a point in the request. A filter lets you change a value and return it. Both are registered with add_filter() or add_action(), which take the hook name, your callback, a priority (default 10) and the number of arguments your callback accepts (default 1).

The argument count is the mistake we see most. If a hook passes five values and you leave the default, your callback receives only the first one. Where the table below says the hook passes an object, many BuddyPress save hooks pass the object by reference through do_action_ref_array(), so changes you make to its properties apply to the item being saved.

The Type column in each table says Action or Filter. The Arguments column lists the values passed, in order, taken from the docblock above the hook in the source. Hooks with no arguments say none.

Which hooks load BuddyPress?

These fire during setup. Load order decides where your own registration code belongs: after bp_include the component files exist, after bp_setup_globals the component globals are set, and bp_setup_nav is where profile tabs are added. The exact order on a normal page load is in the firing-order section further down. Note that bp_setup_nav does not run on init in BuddyPress 12 and later: with the default rewrites parser it runs on the WordPress parse_query action, so it is not available on admin or REST requests.

Hook

Type

Source file

Arguments

What it is for

bp_loaded

Action

bp-core/bp-core-dependency.php

none

Fires on plugins_loaded. Use it to check that BuddyPress is active before touching its functions.

bp_include

Action

bp-core/bp-core-dependency.php

none

Component files load here. Include your own BuddyPress-dependent files at this point.

bp_init

Action

bp-core/bp-core-dependency.php

none

Fires on init. A general-purpose point to run your own setup that needs BuddyPress data.

bp_setup_globals

Action

bp-core/bp-core-dependency.php

none

Component globals such as slugs and root URLs are set. Register a component-level global from your own plugin here.

bp_setup_nav

Action

bp-core/bp-core-dependency.php

none

Add member profile navigation. Call bp_core_new_nav_item() from a callback here to create a profile tab.

bp_setup_admin_bar

Action

bp-core/bp-core-dependency.php

Empty array

Add items to the BuddyPress section of the admin bar. Fires on admin_bar_menu at priority 20.

Registering a profile tab belongs on bp_setup_nav. Here is the minimal shape of a callback, checked on 15 November 2026:

<?php
// Add a "Portfolio" tab to member profiles.
add_action( 'bp_setup_nav', function () {
	bp_core_new_nav_item( array(
		'name'            => __( 'Portfolio', 'my-plugin' ),
		'slug'            => 'portfolio',
		'position'        => 80,
		'screen_function' => 'my_plugin_portfolio_screen',
		'default_subnav_slug' => 'portfolio',
	) );
} );

The screen_function is your own function that loads a template; it is not shown here because it depends on your theme. Test the tab on a member profile and in the admin bar before shipping.

Which hooks cover sign-up and members?

Registration and account activation fire these. The two actions give you the new user ID, which is what most integrations need, for example to create a record in a CRM or to add the user to a group after activation.

Hook

Type

Source file

Arguments

What it is for

bp_core_signup_user

Action

bp-members/bp-members-functions.php

user_id (or WP_Error), user_login, user_password, user_email, usermeta

Fires after a sign-up is recorded. The first argument is true on success and a WP_Error on failure, so check it first.

bp_core_activated_user

Action

bp-members/bp-members-functions.php

user_id, key, user

Fires when the activation key is accepted and the account becomes active. A good place to assign a default group or role.

bp_signup_validate

Action

bp-members/screens/register.php

none

Runs while the registration form is validated. Add your own sign-up errors here.

bp_core_validate_user_signup

Filter

bp-members/bp-members-functions.php

result

Filter the validation result array, including its errors, before BuddyPress acts on it.

bp_members_get_user_url

Filter

bp-members/bp-members-functions.php

url, user_id, slug, path_chunks

Filter a member profile URL. Added in BuddyPress 12.0.0 and the replacement for the removed profile domain filter.

A common request is to send new members to a group the moment they activate. This is safe to run on activation because BuddyPress has created the user by then:

<?php
// Join every newly activated member to group 12 (use your own group ID).
add_action( 'bp_core_activated_user', function ( $user_id ) {
	if ( bp_is_active( 'groups' ) ) {
		groups_join_group( 12, $user_id );
	}
} );

Checked on 15 November 2026. Replace 12 with a real group ID, and note that groups_join_group() is itself a function that fires the groups_join_group action listed below, so any other callback on that action also runs.

Which hooks change the directory?

The Members directory and single-member header have template hooks. These are fired from template files and template functions, so a theme that overrides the templates can drop them. Both Nouveau and the legacy pack call the three header-related actions below.

Hook

Type

Source file

Arguments

What it is for

bp_directory_members_item

Action

bp-templates/bp-nouveau/includes/members/template-tags.php

none

Extra content inside each member item. In Nouveau it only runs on the Members directory and only when a callback is hooked.

bp_directory_members_item_meta

Action

bp-templates/bp-nouveau/includes/members/functions.php

none

Extra metadata inside the directory member item. Added in BuddyPress 6.0.0 when the item hook was repositioned.

bp_before_member_header

Action

bp-templates/bp-nouveau/includes/members/template-tags.php

none

Output before the single member header.

bp_after_member_header

Action

bp-templates/bp-nouveau/includes/members/template-tags.php

none

Output after the single member header. Use it for a banner or status line.

Which hooks cover profile fields?

Extended profile (xProfile) hooks fire around saving and showing field data. Note that xprofile_updated_profile fires from two places: the front-end profile edit screen and the wp-admin user profile screen, so a callback runs for both.

Hook

Type

Source file

Arguments

What it is for

xprofile_updated_profile

Action

bp-xprofile/screens/edit.php and bp-xprofile/classes/class-bp-xprofile-user-admin.php

user_id, posted_field_ids, errors, old_values, new_values

Fires after a member profile is saved from the front end or from wp-admin. The two value arrays were added in 2.6.0.

xprofile_data_before_save

Action

bp-xprofile/classes/class-bp-xprofile-profiledata.php

profile_data (object, by reference)

Fires before one field value is saved. Edit the data object to normalise input.

xprofile_field_after_save

Action

bp-xprofile/classes/class-bp-xprofile-field.php

field (object)

Fires after a profile field definition is saved in the admin. Use it to sync field settings elsewhere.

xprofile_data_is_valid_field

Filter

bp-xprofile/classes/class-bp-xprofile-profiledata.php

retval (bool), profile_data (object)

Filter whether the data for a field counts as valid. Return false to reject the value.

bp_get_the_profile_field_value

Filter

bp-xprofile/bp-xprofile-template.php

value, type, id

Filter a field value as it is displayed. Use it to turn plain text into a link or format a number.

For custom validation, hook xprofile_data_is_valid_field. This sketch rejects a website field that is not a URL; the field ID is a placeholder you replace with your own. Checked on 15 November 2026:

<?php
// Reject a non-URL value for xProfile field 7 (replace 7 with your field ID).
add_filter( 'xprofile_data_is_valid_field', function ( $is_valid, $profile_data ) {
	if ( 7 === (int) $profile_data->field_id && '' !== $profile_data->value ) {
		return (bool) filter_var( $profile_data->value, FILTER_VALIDATE_URL );
	}
	return $is_valid;
}, 10, 2 );

Returning false stops that value from saving. Show your own message on the edit screen as well, because the filter does not output text.

Which hooks cover activity?

Activity hooks cover the feed, posting and comments. The two save hooks pass the whole activity object by reference, so you can read or change its properties before it reaches the database.

Hook

Type

Source file

Arguments

What it is for

bp_activity_before_save

Action

bp-activity/classes/class-bp-activity-activity.php

activity (object, by reference)

Fires before an activity item is written. Change $activity->content here to filter or tag content.

bp_activity_after_save

Action

bp-activity/classes/class-bp-activity-activity.php

activity (object, by reference)

Fires after an item is saved. The ID now exists, so you can attach activity meta.

bp_activity_posted_update

Action

bp-activity/bp-activity-functions.php

content, user_id, activity_id

Fires after a status update is posted through bp_activity_post_update().

bp_activity_comment_posted

Action

bp-activity/bp-activity-functions.php

comment_id, r (parsed args), activity

Fires after a comment on an activity item is posted. The third argument is the item being commented on.

bp_activity_can_comment

Filter

bp-activity/bp-activity-template.php

can_comment (bool), activity_type

Filter whether an activity type allows comments. Return false to turn comments off for a type.

bp_register_activity_actions

Action

bp-activity/bp-activity-functions.php

none

Register your own activity types here with bp_activity_set_action(), so they show a readable label in the feed.

bp_before_activity_entry

Action

bp-templates/bp-legacy/buddypress/activity/entry.php (Nouveau builds the same name)

none

Output before each entry in the loop.

bp_after_activity_entry

Action

bp-templates/bp-legacy/buddypress/activity/entry.php (Nouveau builds the same name)

none

Output after each entry in the loop.

Nouveau does not write these two names in its template. It builds them in bp_nouveau_activity_hook() from a prefix, a position and a suffix, so a plain search for the string in the Nouveau folder comes back empty even though the hook fires. This is why we cite the legacy file in the table.

Here is a small use of the before-save action: add a trailing note to updates posted by one role. The role name is an example. Checked on 15 November 2026:

<?php
add_action( 'bp_activity_before_save', function ( $activity ) {
	if ( 'activity_update' !== $activity->type ) {
		return;
	}
	$user = get_userdata( $activity->user_id );
	if ( $user && in_array( 'moderator', (array) $user->roles, true ) ) {
		$activity->content .= ' [mod]';
	}
} );

Which hooks cover groups?

Group hooks cover creation, membership and invitations. Since BuddyPress 10.0.0 the join and leave actions pass the group object as a third argument, so set your argument count to 3 if you need it.

Hook

Type

Source file

Arguments

What it is for

groups_group_after_save

Action

bp-groups/classes/class-bp-groups-group.php

group (object, by reference)

Fires after a group is saved, for both create and update.

groups_created_group

Action

bp-groups/bp-groups-functions.php

id, group

Fires after a new group is created. Create group-level resources here.

groups_details_updated

Action

bp-groups/bp-groups-functions.php

id, old_group, notify_members

Fires after group name or description changes. The old group object lets you compare.

groups_join_group

Action

bp-groups/bp-groups-functions.php

group_id, user_id, group

Fires when a member joins. The group argument was added in 10.0.0.

groups_leave_group

Action

bp-groups/bp-groups-functions.php

group_id, user_id, group

Fires when a member leaves. The group argument was added in 10.0.0.

groups_promote_member

Action

bp-groups/bp-groups-functions.php

group_id, user_id, status

Fires when a member becomes a moderator or admin. The status is the new role.

groups_ban_member

Action

bp-groups/bp-groups-functions.php

group_id, user_id

Fires when a member is banned from a group.

groups_invite_user

Action

bp-groups/bp-groups-functions.php

r (parsed args), created

Fires after an invitation is created. The second argument is the invitation ID, or false if it failed.

groups_delete_group

Action

bp-groups/bp-groups-functions.php

group_id

Fires after a group is deleted. Clean up your own data tied to the group.

bp_groups_user_can_send_invites

Filter

bp-groups/bp-groups-template.php

can_send_invites, group_id, invite_status, user_id

Filter whether a user can send invitations for a group. The user ID argument was added in 2.2.0.

If your plugin stores its own rows for a group, groups_delete_group is the place to remove them.

Which hooks cover messages?

Private message hooks fire from the message class and the send function. The sent action is the clean point to notify an outside system because the message already exists.

Hook

Type

Source file

Arguments

What it is for

messages_message_before_save

Action

bp-messages/classes/class-bp-messages-message.php

message (object, by reference)

Fires before a message is stored. Change the subject or body on the object.

messages_message_sent

Action

bp-messages/bp-messages-functions.php

message (by reference), r (parsed args)

Fires after a message is sent. The parsed-arguments value was added in 11.0.0.

messages_thread_mark_as_read

Action

bp-messages/classes/class-bp-messages-thread.php

thread_id, user_id, num_rows

Fires after a thread is marked read for a user. The row count is false on error.

bp_messages_recipients

Filter

bp-messages/actions/compose.php

recipients

Filter the recipients array on the compose screen before the message is sent.

Which hooks cover notifications?

Notification hooks cover saving and rendering. Registering a notification text for your own component uses the component callback; the filter in the last row is the fallback for components that do not have one.

Hook

Type

Source file

Arguments

What it is for

bp_notification_after_save

Action

bp-notifications/classes/class-bp-notifications-notification.php

notification (object)

Fires after a notification is stored. Send an email or push message from here.

bp_notifications_get_registered_components

Filter

bp-notifications/bp-notifications-functions.php

component_names, active_components

Add your own component name so its notifications are counted and listed.

bp_notifications_get_notifications_for_user

Filter

bp-notifications/bp-notifications-functions.php

content, item_id, secondary_item_id, action_item_count, format, component_action_name, component_name, id

Filter the text of a notification when a component has no callback of its own. Test the sixth value, not the first, to see the action.

If you build a custom notification type, our comparison of community notification systems shows what members expect from email and on-site alerts.

Which hooks cover friendships?

Friend connections fire hooks for each state change. The request hook is a variable hook: BuddyPress builds its name from the word friends_friendship_ plus the action (requested or accepted), so a search for the full name in the source finds only the comment above it. It still fires, and BuddyPress itself hooks into it for notifications and cache clearing.

Hook

Type

Source file

Arguments

What it is for

friends_friendship_requested

Action

bp-friends/bp-friends-functions.php (variable hook)

id, initiator_user_id, friend_user_id, friendship

Fires when a friend request is sent. Built as a variable hook name.

friends_friendship_accepted

Action

bp-friends/bp-friends-functions.php

id, initiator_user_id, friend_user_id, friendship

Fires when a request is accepted, or when a friendship is created already accepted.

friends_friendship_deleted

Action

bp-friends/bp-friends-functions.php

friendship_id, initiator_userid, friend_userid

Fires when a friendship is removed.

friends_friendship_rejected

Action

bp-friends/bp-friends-functions.php

friendship_id, friendship (by reference)

Fires when the receiving member rejects a request.

friends_friendship_withdrawn

Action

bp-friends/bp-friends-functions.php

friendship_id, friendship (by reference)

Fires when the sender withdraws a request. Added in 1.9.0.

That is 50 hooks across nine components, all present in the 14.5.4 source.

Which hooks were removed or renamed?

BuddyPress 12.0 moved URL handling to the WordPress rewrite system and deprecated a group of hooks and functions. Deprecated hooks still fire in 14.5.4, but each one logs a deprecation notice, and some can be removed in a later major version. The list below comes from bp-core/deprecated/12.0.php in 14.5.4, and 14.0 added one more.

Deprecated hook

Deprecated in

Use instead

bp_core_get_user_domain

12.0.0

bp_members_get_user_url

bp_core_get_username

12.0.0

bp_members_get_user_slug

bp_core_get_root_domain

12.0.0

bp_rewrites_get_root_url

bp_get_group_permalink

12.0.0

bp_get_group_url

bp_get_group_admin_permalink

12.0.0

bp_get_group_manage_url

bp_get_displayed_user_link

12.0.0

bp_displayed_user_url

bp_get_loggedin_user_link

12.0.0

bp_loggedin_user_url

bp_directory_pages

12.0.0

No replacement

groups_header_tabs

12.0.0

No replacement

bp_use_wp_admin_bar

14.0.0

No replacement

Not every hook name you will find online exists. We searched the 14.5.4 source for the following names that circulate in tutorials and AI answers, including an earlier version of this post, and found no matching action or filter: xprofile_validated_field, bp_messages_message_validated, bp_notifications_delete_notifications_on_read, bp_core_default_component and groups_member_can_send_invite. Two other names are real functions that people mistake for hooks: bp_group_is_visible() and bp_core_get_active_components(). Call them, do not hook them.

Here is the upgrade for the most common one. Checked on 15 November 2026:

<?php
// Before (deprecated since BuddyPress 12.0.0):
// $url = bp_core_get_user_domain( $user_id );

// After:
$url = bp_members_get_user_url( $user_id );

The optional second argument is an array of path chunks, documented in the docblock above bp_members_get_user_url() in bp-members/bp-members-functions.php. The single-argument form returns the profile root.

In what order do hooks fire?

The order below is read from bp-core/bp-core-actions.php in 14.5.4 for a front-end request with the default rewrites parser. Hook names on the left are the BuddyPress actions; the WordPress action that triggers each one is on the right. If your code runs too early, move to a later hook. If it runs too late, move earlier. This replaces the order in the earlier version of this post, which did not match the source.

  1. bp_loaded on plugins_loaded. Callbacks on it then fire bp_setup_components and bp_include.
  2. bp_init on init. Callbacks on it then fire bp_setup_globals.
  3. bp_setup_canonical_stack then bp_setup_nav, on parse_query.
  4. bp_setup_admin_bar on admin_bar_menu, priority 20.
  5. bp_template_redirect on template_redirect.
  6. bp_enqueue_scripts on wp_enqueue_scripts.

If a site runs the legacy query parser (set through the BP Classic plugin or its filter), the canonical stack and nav hooks run on bp_init instead. We did not test that mode.

Common mistakes people report

These are the problems that come up most in BuddyPress support threads and source comments. Checked on 15 November 2026.

  • Calling the old profile URL function after upgrading to 12.0. Plugins that still use the deprecated function log a notice, as in this wpForo bug report. Replace calls with bp_members_get_user_url().
  • Expecting the directory item hook to run on any page. In Nouveau it runs only on the Members directory and only when something is hooked, as described near the top of this page and in the BuddyPress source.
  • Leaving the argument count at 1. Hooks such as the group join action pass three values. Without the count in add_action() you get only the first. See the WordPress reference.
  • Running a callback twice on profile save. xprofile_updated_profile fires from both the front-end screen and wp-admin, so a callback with side effects, such as sending an email, can run once per surface.
  • Searching the source for a variable hook name. The friend request hook and the Nouveau activity entry hooks are built from strings, so a plain search misses them. Search for the prefix.
  • Fatal errors after a major BuddyPress upgrade. Several people in the BuddyPress 12.0.0 support thread report errors from calls to undefined functions after the move to the rewrite system. Test on staging first.

Which hooks should you use first?

Most customisation jobs need only a handful. If you are new to BuddyPress, start with these and look further only when the task needs it.

You want to

Start with

Type

Add text under each member in the directory

bp_directory_members_item

Action

Do something after a user activates

bp_core_activated_user

Action

Change a profile link

bp_members_get_user_url

Filter

Reject bad profile data

xprofile_data_is_valid_field

Filter

Change or tag a feed post before saving

bp_activity_before_save

Action

React to someone joining a group

groups_join_group

Action

Act after a message sends

messages_message_sent

Action

Add a profile tab

bp_setup_nav

Action

Hooks when you build on BuddyNext

These hooks belong to BuddyPress. Our own community platform, BuddyNext, is a separate plugin with its own hooks and templates, so a callback written for BuddyPress will not fire there. Check the BuddyNext documentation for its equivalents before you port code. If you want a community theme for BuddyPress, our Reign and BuddyX themes are built for it, but check any hook you rely on against the theme’s template overrides.

The honest limit of this page: it lists 50 hooks out of the hundreds in the plugin. We chose the ones most useful for customisation and verified each one, but we did not run every example on every theme. Test on staging before you ship.

Frequently asked questions

How many hooks does BuddyPress have?

It has well over a thousand do_action and apply_filters calls. A search of the 14.5.4 source tree finds more than 2,700 matching lines, and the count includes template files and deprecated code, so treat it as a rough scale rather than an exact figure.

Where is the full hook list?

There is no official single page that stays current with the source. Search the BuddyPress source on GitHub for do_action and apply_filters, or read the docblocks above each call, which list the arguments and the version a hook was added.

Does bp_directory_members_item work in Nouveau?

Yes, with two conditions: the page is the Members directory and a callback is hooked. Use the filter named bp_nouveau_member_extra_content_in_members_directory to allow it elsewhere.

Is bp_core_get_user_domain removed?

It is deprecated since 12.0.0, not removed, in the 14.5.4 source. It still works and logs a deprecation notice. Switch to bp_members_get_user_url().

Do these hooks work with BuddyBoss?

Not necessarily. BuddyBoss Platform is a separate fork with its own templates, and we did not test these hooks on it. Check the platform documentation before assuming a hook fires.

Related reading

Everything on this page was checked on 15 November 2026 against BuddyPress 14.5.4. If a hook behaves differently on your version, tell us and we will update the table.

Part of the Wbcom Designs family

The all-in-one WordPress community stack

Also ours: wbcomdesigns.comvapvarun.combrndle.com