BuddyPress Hooks Cheat Sheet: 50 Essential Actions and Filters

Why You Need a BuddyPress Hooks Reference

BuddyPress fires hundreds of actions and filters across its codebase. Knowing which hook to use and when it fires is the difference between a clean customization and a fragile hack that breaks on the next update.

This cheat sheet organizes the 50 most useful BuddyPress hooks by component. Each entry includes the hook name, type, when it fires, and practical usage. Bookmark this page, you’ll come back to it every time you build a BuddyPress plugin or customize a community site.

All hooks listed here work with BuddyPress 12.x and later. Parameter counts and signatures are verified against the current source code.

Member Profile Hooks

Profile hooks fire when members view, edit, or update their profiles. These are essential for adding custom fields, validation, and third-party integrations.

Hook Name	Type	When It Fires	Parameters
`bp_core_signup_user`	Action	After a new user signs up	user_id, user_login, user_password, user_email, usermeta
`bp_core_activated_user`	Action	After account activation	user_id, key, user
`bp_before_profile_field_content`	Action	Before each profile field renders	–
`bp_after_profile_field_content`	Action	After each profile field renders	–
`xprofile_updated_profile`	Action	After profile save completes	user_id, posted_field_ids, is_new_profile, has_errors
`xprofile_data_before_save`	Action	Before a profile field value saves	field_data_object
`bp_xprofile_field_type`	Filter	Filter the field type during render	type, field_id
`xprofile_validated_field`	Filter	Validate field data before save	is_valid, field

Practical Example: Validate a Custom Profile Field

One of the most common needs is validating profile field data before it saves. The xprofile_validated_field filter lets you reject bad input with a custom error message. Here’s how to validate a Website URL field:

This pattern works for phone numbers, social media handles, zip codes, any field that needs format validation beyond what BuddyPress provides natively.

Activity Stream Hooks

Activity hooks control what appears in the sitewide and member activity feeds. Use these to add custom activity types, filter content, or inject actions.

Hook Name	Type	When It Fires	Parameters
`bp_activity_before_save`	Action	Before activity item saves to DB	activity_object
`bp_activity_after_save`	Action	After activity item saves	activity_object
`bp_activity_posted_update`	Action	After a status update posts	content, user_id, activity_id
`bp_before_activity_entry`	Action	Before each activity entry renders in loop	–
`bp_after_activity_entry`	Action	After each activity entry renders	–
`bp_activity_custom_update`	Action	Custom activity type handler	content, user_id, activity_id
`bp_get_activity_content_body`	Filter	Filter activity content before display	content
`bp_activity_check_blacklist_keys`	Filter	Check content against spam keywords	is_spam, activity
`bp_activity_set_action`	Filter	Modify the activity action string	action, activity
`bp_activity_can_comment`	Filter	Control whether comments are allowed	can_comment, activity_type

Practical Example: Register a Custom Activity Type

BuddyPress activity types are how different actions appear in the feed, “posted an update,” “joined a group,” etc. Register your own types for plugin-specific actions:

This is how plugins like BuddyPress Member Blog, BuddyPress Polls, and event plugins add their activity types.

Groups Hooks

Group hooks cover creation, membership changes, and group page rendering. These are critical for plugins that extend group functionality.

Hook Name	Type	When It Fires	Parameters
`groups_group_after_save`	Action	After a group saves (create or update)	group_object
`groups_created_group`	Action	After a new group is created	group_id, member, group
`groups_join_group`	Action	When a member joins a group	group_id, user_id
`groups_leave_group`	Action	When a member leaves a group	group_id, user_id
`groups_promote_member`	Action	When a member is promoted (mod/admin)	group_id, user_id, status
`groups_demote_member`	Action	When a member is demoted	group_id, user_id
`groups_ban_member`	Action	When a member is banned	group_id, user_id
`bp_before_group_header`	Action	Before group header renders	–
`bp_group_is_visible`	Filter	Control group visibility	is_visible, group
`groups_member_can_send_invite`	Filter	Control who can send group invites	can_invite, user_id, group_id

Practical Example: Auto-Join Users to a Group

A common requirement is automatically adding new users to a default group. Here’s how to do it, including role-based auto-join:

You can extend this pattern to auto-join based on membership tier or custom profile field values. WooCommerce Memberships integration often uses this approach to gate group access behind paid plans.

Private Messaging Hooks

Messaging hooks let you intercept, modify, or extend the BuddyPress private messaging system.

Hook Name	Type	When It Fires	Parameters
`messages_message_before_save`	Action	Before a message saves	message_object
`messages_message_after_save`	Action	After a message saves	message_object
`messages_send_message`	Action	After message is sent successfully	message_data
`bp_before_messages_compose_content`	Action	Before compose form renders	–
`bp_messages_message_validated`	Filter	Validate message before sending	validated, message
`bp_messages_recipients`	Filter	Filter message recipients	recipients, message_info

Practical Example: Block Messages Between Non-Friends

Restrict messaging to connected members only, preventing spam and unwanted contact from strangers:

Notifications Hooks

Notification hooks control how BuddyPress alerts members about activity relevant to them.

Hook Name	Type	When It Fires	Parameters
`bp_notification_after_save`	Action	After notification saves	notification_object
`bp_notifications_delete_notifications_on_read`	Action	When a notification is marked read	notification_id
`bp_notifications_get_registered_components`	Filter	Register notification components	component_names
`bp_notifications_get_notifications_for_user`	Filter	Filter notifications before display	notifications, user_id

Navigation and Template Hooks

These hooks control the BuddyPress navigation menus, member profile tabs, and template loading.

Hook Name	Type	When It Fires	Parameters
`bp_setup_nav`	Action	When member profile navigation registers	–
`bp_setup_admin_bar`	Action	When admin bar items register	wp_admin_nav
`bp_before_member_header`	Action	Before member profile header	–
`bp_after_member_header`	Action	After member profile header	–
`bp_directory_members_item`	Action	Inside each member directory item	–
`bp_get_template_part`	Filter	Filter which template file loads	templates, slug, name
`bp_located_template`	Filter	Filter the located template path	template_path, template_names
`bp_core_get_user_domain`	Filter	Filter member profile URL	domain, user_id

Practical Example: Add a Custom Profile Tab

Adding tabs to member profiles is one of the most requested BuddyPress customizations. Here’s the complete pattern:

This is how plugins add “Portfolio,” “Courses,” “Orders,” or any custom section to member profiles.

Global and Initialization Hooks

These hooks fire during BuddyPress initialization and are used for registering components, loading assets, and setup tasks.

Hook Name	Type	When It Fires	Parameters
`bp_include`	Action	When BP loads component includes	–
`bp_setup_components`	Action	After all components are set up	–
`bp_init`	Action	After BuddyPress fully initializes	–
`bp_loaded`	Action	After BP is fully loaded	–
`bp_enqueue_scripts`	Action	Time to enqueue BP-specific scripts	–
`bp_register_activity_actions`	Action	Time to register activity action types	–
`bp_core_get_active_components`	Filter	Filter which components are active	components
`bp_core_default_component`	Filter	Set the default member profile component	component

Friends and Connections Hooks

Friend hooks fire during connection requests, acceptance, and removal.

Hook Name	Type	When It Fires	Parameters
`friends_friendship_requested`	Action	When a friend request is sent	friendship_id, initiator_id, friend_id
`friends_friendship_accepted`	Action	When a friend request is accepted	friendship_id, initiator_id, friend_id
`friends_friendship_deleted`	Action	When a friendship is removed	friendship_id, initiator_id, friend_id
`friends_friendship_post_delete`	Action	After friendship deletion completes	initiator_id, friend_id

Quick Reference: Hook Firing Order

Understanding when hooks fire relative to each other prevents timing bugs. Here is the BuddyPress initialization sequence:

bp_include, Component files are loaded
bp_setup_components, Components initialize
bp_setup_globals, Global variables set
bp_setup_canonical_stack, URL routing configured
bp_setup_nav, Navigation tabs register
bp_setup_admin_bar, Admin bar items register
bp_init, BuddyPress fully initialized
bp_loaded, Everything is ready
bp_template_redirect, Template loading begins
bp_enqueue_scripts, Scripts and styles enqueue

If your hook callback runs too early (before the data it needs exists), move it to a later hook in this sequence. If it runs too late (after the output it should modify), move it earlier.

Best Practices for Using BuddyPress Hooks

Always Check Hook Parameters

BuddyPress hooks pass different numbers of parameters. Always specify the correct number in your add_action() or add_filter() call. Missing the parameter count means your callback receives null values instead of the data you expect.

Use Priority Numbers Strategically

The default priority is 10. Use lower numbers (1-9) to run before other plugins. Use higher numbers (11-99) to run after. This matters when multiple plugins hook into the same action, priority determines execution order.

Prefer Filters Over Direct Database Queries

If a filter exists for the data you need to modify, use it. Filters are forward-compatible, direct database queries break when table structures change between BuddyPress versions.

Test With BuddyPress Debug Mode

Add define('BP_DEBUG', true) to wp-config.php during development. This enables additional error reporting specific to BuddyPress and helps catch hook-related issues early.

Document Your Hook Usage

Every custom hook callback should have a comment explaining what it does and why. Future developers (including future you) will thank you when they need to debug or modify the behavior.

Keep This Cheat Sheet Handy

These 50 hooks cover the vast majority of BuddyPress customization needs. Whether you are building a plugin, customizing a theme, or integrating third-party services, the right hook makes the job clean and maintainable.

For complex BuddyPress projects that go beyond hooks, custom components, REST API integrations, or full platform builds, talk to our BuddyPress development team for a free consultation.

Book a Free BuddyPress Consultation

Bookmark this page and reference it whenever you start a new BuddyPress project. The hooks listed here are stable across versions and form the foundation of every well-built BuddyPress customization.