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.

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 |
|---|---|---|---|---|
| Action |
| none | Fires on plugins_loaded. Use it to check that BuddyPress is active before touching its functions. |
| Action |
| none | Component files load here. Include your own BuddyPress-dependent files at this point. |
| Action |
| none | Fires on init. A general-purpose point to run your own setup that needs BuddyPress data. |
| Action |
| none | Component globals such as slugs and root URLs are set. Register a component-level global from your own plugin here. |
| Action |
| none | Add member profile navigation. Call |
| Action |
| 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 |
|---|---|---|---|---|
| Action |
| 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. |
| Action |
| 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. |
| Action |
| none | Runs while the registration form is validated. Add your own sign-up errors here. |
| Filter |
| result | Filter the validation result array, including its errors, before BuddyPress acts on it. |
| Filter |
| 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 |
|---|---|---|---|---|
| Action |
| none | Extra content inside each member item. In Nouveau it only runs on the Members directory and only when a callback is hooked. |
| Action |
| none | Extra metadata inside the directory member item. Added in BuddyPress 6.0.0 when the item hook was repositioned. |
| Action |
| none | Output before the single member header. |
| Action |
| 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 |
|---|---|---|---|---|
| Action |
| 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. |
| Action |
| profile_data (object, by reference) | Fires before one field value is saved. Edit the data object to normalise input. |
| Action |
| field (object) | Fires after a profile field definition is saved in the admin. Use it to sync field settings elsewhere. |
| Filter |
| retval (bool), profile_data (object) | Filter whether the data for a field counts as valid. Return false to reject the value. |
| Filter |
| 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 |
|---|---|---|---|---|
| Action |
| activity (object, by reference) | Fires before an activity item is written. Change |
| Action |
| activity (object, by reference) | Fires after an item is saved. The ID now exists, so you can attach activity meta. |
| Action |
| content, user_id, activity_id | Fires after a status update is posted through |
| Action |
| 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. |
| Filter |
| can_comment (bool), activity_type | Filter whether an activity type allows comments. Return false to turn comments off for a type. |
| Action |
| none | Register your own activity types here with |
| Action |
| none | Output before each entry in the loop. |
| Action |
| 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 |
|---|---|---|---|---|
| Action |
| group (object, by reference) | Fires after a group is saved, for both create and update. |
| Action |
| id, group | Fires after a new group is created. Create group-level resources here. |
| Action |
| id, old_group, notify_members | Fires after group name or description changes. The old group object lets you compare. |
| Action |
| group_id, user_id, group | Fires when a member joins. The group argument was added in 10.0.0. |
| Action |
| group_id, user_id, group | Fires when a member leaves. The group argument was added in 10.0.0. |
| Action |
| group_id, user_id, status | Fires when a member becomes a moderator or admin. The status is the new role. |
| Action |
| group_id, user_id | Fires when a member is banned from a group. |
| Action |
| r (parsed args), created | Fires after an invitation is created. The second argument is the invitation ID, or false if it failed. |
| Action |
| group_id | Fires after a group is deleted. Clean up your own data tied to the group. |
| Filter |
| 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 |
|---|---|---|---|---|
| Action |
| message (object, by reference) | Fires before a message is stored. Change the subject or body on the object. |
| Action |
| message (by reference), r (parsed args) | Fires after a message is sent. The parsed-arguments value was added in 11.0.0. |
| Action |
| thread_id, user_id, num_rows | Fires after a thread is marked read for a user. The row count is false on error. |
| Filter |
| 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 |
|---|---|---|---|---|
| Action |
| notification (object) | Fires after a notification is stored. Send an email or push message from here. |
| Filter |
| component_names, active_components | Add your own component name so its notifications are counted and listed. |
| Filter |
| 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 |
|---|---|---|---|---|
| Action |
| id, initiator_user_id, friend_user_id, friendship | Fires when a friend request is sent. Built as a variable hook name. |
| Action |
| id, initiator_user_id, friend_user_id, friendship | Fires when a request is accepted, or when a friendship is created already accepted. |
| Action |
| friendship_id, initiator_userid, friend_userid | Fires when a friendship is removed. |
| Action |
| friendship_id, friendship (by reference) | Fires when the receiving member rejects a request. |
| Action |
| 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 |
|---|---|---|
| 12.0.0 |
|
| 12.0.0 |
|
| 12.0.0 |
|
| 12.0.0 |
|
| 12.0.0 |
|
| 12.0.0 |
|
| 12.0.0 |
|
| 12.0.0 | No replacement |
| 12.0.0 | No replacement |
| 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.
bp_loadedonplugins_loaded. Callbacks on it then firebp_setup_componentsandbp_include.bp_initoninit. Callbacks on it then firebp_setup_globals.bp_setup_canonical_stackthenbp_setup_nav, onparse_query.bp_setup_admin_baronadmin_bar_menu, priority 20.bp_template_redirectontemplate_redirect.bp_enqueue_scriptsonwp_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_profilefires 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 |
| Action |
Do something after a user activates |
| Action |
Change a profile link |
| Filter |
Reject bad profile data |
| Filter |
Change or tag a feed post before saving |
| Action |
React to someone joining a group |
| Action |
Act after a message sends |
| Action |
Add a profile tab |
| 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
- How to use the BuddyPress plugin in WordPress
- Redirect BuddyPress members after login
- Community notification systems compared
- BuddyPress not generating default pages
- BuddyPress performance optimization
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.


