Filters Reference

Filters let you intercept and change values at every stage of the suggestion pipeline. Unlike actions, filters must return the (possibly modified) value.

Compatibility score filters

These filters run inside buddypress_friend_follow_compatibility_score().

`bp_suggestions_pre_compatibility_score`

Return a non-false value to bypass the entire scoring algorithm for a specific pair.

apply_filters( 'bp_suggestions_pre_compatibility_score', false, $user_id1, $user_id2 );

Parameter	Type	Default	Description
`$pre_score`	`int\|false`	`false`	Return an integer 0–100 to short-circuit scoring; return `false` to let the engine run
`$user_id1`	`int`	—	First user
`$user_id2`	`int`	—	Second user

Example — always return 0 for admin users:

add_filter( 'bp_suggestions_pre_compatibility_score', function( $score, $user_id1, $user_id2 ) {
    if ( user_can( $user_id1, 'manage_options' ) || user_can( $user_id2, 'manage_options' ) ) {
        return 0;
    }
    return $score; // false = run normally
}, 10, 3 );

`bp_suggestions_score_disabled`

Filters the score returned when the “Enable Profile Matching” master toggle is off.

apply_filters( 'bp_suggestions_score_disabled', 0, $user_id1, $user_id2 );

Default is 0. Override only if you have an alternate scoring source you want to use even when the built-in engine is disabled.

`bp_suggestions_score_invalid_user_ids`

Filters the score returned when one or both user IDs are invalid.

apply_filters( 'bp_suggestions_score_invalid_user_ids', 0, $user_id1, $user_id2 );

Default is 0.

`bp_suggestions_score_cache_key`

Change the object-cache key used for a score pair.

apply_filters( 'bp_suggestions_score_cache_key', $cache_key, $user_id1, $user_id2 );

Parameter	Type	Description
`$cache_key`	`string`	Default: `'bffs_score_{lower_id}_{higher_id}'`

IDs are always sorted ascending before the key is built, so the key is the same regardless of argument order.

`bp_suggestions_cached_score`

Filters the score when it is served from the object cache.

apply_filters( 'bp_suggestions_cached_score', $cached_score, $user_id1, $user_id2 );

`bp_suggestions_match_settings`

Override the full settings array before the score engine reads it.

apply_filters( 'bp_suggestions_match_settings', $bffs_general_setting, $user_id1, $user_id2 );

Parameter	Type	Description
`$bffs_general_setting`	`array`	The `bffs_general_setting` option value

Use this to apply different field weights for specific user pairs or roles.

`bp_suggestions_default_score`

Filters the baseline score before field matching begins. This is the “universal match percentage” value from General settings.

apply_filters( 'bp_suggestions_default_score', $default_score, $user_id1, $user_id2 );

`bp_suggestions_score_no_match_data`

Filters the score returned when no fields are configured for matching in the admin.

apply_filters( 'bp_suggestions_score_no_match_data', $score, $user_id1, $user_id2 );

`bp_suggestions_all_profile_fields`

Override the full xProfile field structure before field comparison.

apply_filters( 'bp_suggestions_all_profile_fields', $all_fields, $user_id1, $user_id2 );

Parameter	Type	Description
`$all_fields`	`array`	Field definitions keyed by field ID

`bp_suggestions_match_field_ids`

Filter the list of field IDs that the engine will compare.

apply_filters( 'bp_suggestions_match_field_ids', $field_ids, $user_id1, $user_id2 );

Parameter	Type	Description
`$field_ids`	`array`	Integer field IDs configured in the admin

`bp_suggestions_user1_profile_data`

Filter the profile data fetched for the first user.

apply_filters( 'bp_suggestions_user1_profile_data', $user1_data, $user_id1 );

Parameter	Type	Description
`$user1_data`	`array`	Field data keyed by field ID

`bp_suggestions_user2_profile_data`

Filter the profile data fetched for the second user.

apply_filters( 'bp_suggestions_user2_profile_data', $user2_data, $user_id2 );

Same structure as bp_suggestions_user1_profile_data.

`bp_suggestions_each_match_data`

Filter each field’s match configuration before it is evaluated.

apply_filters( 'bp_suggestions_each_match_data', $match_data, $user_id1, $user_id2 );

Parameter	Type	Description
`$match_data`	`array`	Contains `field_id`, `percentage`, `stop_match`

`bp_suggestions_field_value_user1`

Filter the resolved value for a specific field for the first user.

apply_filters( 'bp_suggestions_field_value_user1', $field1, $field_id, $user_id1, $user_id2 );

`bp_suggestions_field_value_user2`

Filter the resolved value for a specific field for the second user.

apply_filters( 'bp_suggestions_field_value_user2', $field2, $field_id, $user_id1, $user_id2 );

Suggestion list filters

These filters run inside bffs_get_suggestion_members().

`bp_suggestions_max_members`

Change the maximum number of suggestions returned.

apply_filters( 'bp_suggestions_max_members', $max_members, $user_id, $suggest );

Parameter	Type	Description
`$max_members`	`int`	Configured limit from admin settings
`$suggest`	`string`	`'friends'` or `'follow'`

`bp_suggestions_percentage_criteria`

Change the minimum match score a candidate must reach to be included.

apply_filters( 'bp_suggestions_percentage_criteria', $percentage_criteria, $user_id, $suggest );

Parameter	Type	Description
`$percentage_criteria`	`int`	Minimum score (0–100)

`bp_suggestions_suggestion_type`

Override the suggestion mode for a specific user.

apply_filters( 'bp_suggestions_suggestion_type', $suggest, $user_id );

Parameter	Type	Description
`$suggest`	`string`	`'friends'` or `'follow'`

`bp_suggestions_excluded_users`

Filter the exclusion list before it is cached. This is the last opportunity to add or remove user IDs before the list is stored.

apply_filters( 'bp_suggestions_excluded_users', $exclude_user, $user_id, $suggest );

Parameter	Type	Description
`$exclude_user`	`array`	IDs of users who will not appear as suggestions

Example — exclude users of a specific BuddyPress member type:

add_filter( 'bp_suggestions_excluded_users', function( $exclude_user, $user_id, $suggest ) {
    $staff = get_users( array(
        'meta_key'   => 'bp_member_type',
        'meta_value' => 'staff',
        'fields'     => 'ID',
    ) );
    return array_merge( $exclude_user, $staff );
}, 10, 3 );

`bp_suggestions_final_exclude_list`

Filters the complete exclusion list after dismissed suggestions and the viewer’s own ID have been added. This runs just before the pool query.

apply_filters( 'bp_suggestions_final_exclude_list', $exclude_user, $user_id, $suggest );

`bp_suggestions_final_user_list_arguments`

Filter the arguments passed to get_users() when fetching the candidate pool.

apply_filters( 'bp_suggestions_final_user_list_arguments', $bp_suggested_users_arguments, $user_id, $suggest );

Parameter	Type	Description
`$bp_suggested_users_arguments`	`array`	Standard `get_users()` args

`bp_suggestions_potential_users`

Filter the raw pool of candidates returned by get_users() before scoring begins.

apply_filters( 'bp_suggestions_potential_users', $potential_users, $user_id, $suggest );

Parameter	Type	Description
`$potential_users`	`WP_User[]`	All non-excluded users

`bp_suggestions_raw_score`

Filter the raw compatibility score for a candidate immediately after it is calculated (before caching).

apply_filters( 'bp_suggestions_raw_score', $match_score, $user_id, $candidate_id );

`bp_suggestions_match_score`

Filter the match score immediately before comparing it to the percentage threshold. This runs after the score has been loaded from cache, so it fires on every evaluation.

apply_filters( 'bp_suggestions_match_score', $match_score, $user_id, $candidate_id );

`bp_suggestions_should_include_user`

Decide whether a candidate who has cleared the score threshold should actually be included. Return false to exclude.

apply_filters( 'bp_suggestions_should_include_user', $should_add, $candidate_id, $user_id, $match_score, $suggest );

Parameter	Type	Description
`$should_add`	`bool`	`true` by default

Example — exclude users inactive for more than 90 days:

add_filter( 'bp_suggestions_should_include_user', function( $should_add, $candidate_id, $user_id, $score, $suggest ) {
    $last = bp_get_user_last_activity( $candidate_id );
    if ( $last && strtotime( $last ) < strtotime( '-90 days' ) ) {
        return false;
    }
    return $should_add;
}, 10, 5 );

`bp_suggestions_matched_user_default_insertion`

Filter the user ID that is appended to the matched-members array. Return a different ID to swap candidates (unusual but possible for proxy accounts).

apply_filters( 'bp_suggestions_matched_user_default_insertion', $candidate_id, $user_id, $match_score, $suggest );

`bp_suggestions_matched_users`

Filter the complete list of matched member IDs after the scoring loop finishes.

apply_filters( 'bp_suggestions_matched_users', $matched_members, $user_id, $suggest );

Parameter	Type	Description
`$matched_members`	`int[]`	Sorted list of matched user IDs

`bp_suggestions_pool_args`

Filter the bp_core_get_users() arguments used by BFFS_Display when building the scored pool for the display layer. This is separate from the engine pool query above.

apply_filters( 'bp_suggestions_pool_args', $args, $user_id, $context );

Parameter	Type	Description
`$context`	`string`	`'friends'`, `'follow'`, or `'all'`

Template filters

`bp_suggestions_load_template`

Override the resolved path to any template file loaded by bp_suggestions_load_template().

apply_filters( 'bp_suggestions_load_template', $template_part, $file_name );

Parameter	Type	Description
`$template_part`	`string`	Absolute path to the template file
`$file_name`	`string`	Relative filename (e.g. `'list-layout.php'`)

Themes should use directory overrides instead of this filter when possible. See Template Overrides.

`bffs_list_layout_wrapper_id`

Change the id attribute on the <ul> in list layout.

apply_filters( 'bffs_list_layout_wrapper_id', 'members-list', $settings );

`bffs_list_layout_wrapper_classes`

Change the CSS classes on the list layout wrapper.

apply_filters( 'bffs_list_layout_wrapper_classes', 'item-list members-list', $settings );

`bffs_horizontal_layout_wrapper_classes`

Change the CSS classes on the horizontal layout wrapper.

apply_filters( 'bffs_horizontal_layout_wrapper_classes', 'bffs_horizontal_layout horizontal_swiper', $settings );

`bffs_horizontal_slider_wrapper_id`

Change the id attribute on the Swiper wrapper element.

apply_filters( 'bffs_horizontal_slider_wrapper_id', $default_id, $settings );

The default ID includes a random suffix (bp-friend-swiper-slider-{rand}) to support multiple sliders on the same page.

`bffs_horizontal_slider_wrapper_classes`

Change the CSS classes on the Swiper wrapper element.

apply_filters( 'bffs_horizontal_slider_wrapper_classes', $default_classes, $settings );

`bffs_member_permalink`

Override a member’s profile URL inside the suggestion loops.

apply_filters( 'bffs_member_permalink', $permalink, $member_id );

`bffs_member_name`

Override a member’s display name inside the suggestion loops.

apply_filters( 'bffs_member_name', $name, $member_id );

`bffs_member_timeline_url`

Override the timeline/activity URL shown in the slider layout.

apply_filters( 'bffs_member_timeline_url', $url, $member_id );

Default is bp_get_member_permalink() . 'activity/'.

Display filters

`bffs_match_badge_html`

Filter the HTML of the compatibility badge rendered on suggestion cards.

apply_filters( 'bffs_match_badge_html', $badge, $score, $user_id1, $user_id2 );

Parameter	Type	Description
`$badge`	`string`	Full `<span>` element HTML
`$score`	`int`	Compatibility score (0–100)

Notification filters

`bffs_new_suggestion_email_template`

Override the HTML body of the “new suggestions” email.

apply_filters( 'bffs_new_suggestion_email_template', $template );

The placeholder {{{suggestions.list}}} is replaced with the formatted suggestion list.

`bffs_new_suggestion_email_plain`

Override the plain-text version of the “new suggestions” email.

apply_filters( 'bffs_new_suggestion_email_plain', $template );

Use {{suggestions.list}} (double curly braces) for plain text.

`bffs_daily_digest_email_template`

Override the HTML body of the daily digest email.

apply_filters( 'bffs_daily_digest_email_template', $template );

`bffs_daily_digest_email_plain`

Override the plain-text version of the daily digest email.

apply_filters( 'bffs_daily_digest_email_plain', $template );

`bffs_weekly_digest_email_template`

Override the HTML body of the weekly digest email.

apply_filters( 'bffs_weekly_digest_email_template', $template );

`bffs_weekly_digest_email_plain`

Override the plain-text version of the weekly digest email.

apply_filters( 'bffs_weekly_digest_email_plain', $template );

`bffs_suggestions_url`

Override the URL included in email notifications (defaults to the BP members directory).

apply_filters( 'bffs_suggestions_url', $url );

`bffs_weekly_stats`

Override the stats line included in weekly digest emails.

apply_filters( 'bffs_weekly_stats', $stats, $user_id );

Parameter	Type	Description
`$stats`	`string`	Formatted string, e.g. “This week, 12 members joined the community!”

`bffs_skip_hot_matches_on_registration`

Return true to prevent the plugin from checking hot matches when a new member registers. Useful for sites with slow servers or very large user bases.

apply_filters( 'bffs_skip_hot_matches_on_registration', false, $user_id );

`bffs_hot_matches_check_limit`

Cap the number of existing members the hot-match check scores against each new registrant.

apply_filters( 'bffs_hot_matches_check_limit', 25, $user_id );

Default is 25. Lower this if registration is slow on large sites.

`bffs_hot_matches_max_notifications`

Cap how many hot-match notifications a single registration event can send to existing members.

apply_filters( 'bffs_hot_matches_max_notifications', 5, $user_id );

Default is 5.

Admin UI filters

`bffs_admin_tabs`

Add, remove, or reorder tabs in the admin settings page.

apply_filters( 'bffs_admin_tabs', $tabs );

Parameter	Type	Description
`$tabs`	`array`	Keyed by tab slug; each entry has `label`, `icon` (dashicon class), `group`

Groups: 'main', 'settings', 'account'. The shell renders a divider between groups.

Example — add a custom tab:

add_filter( 'bffs_admin_tabs', function( $tabs ) {
    $tabs['integrations'] = array(
        'label' => __( 'Integrations', 'my-plugin' ),
        'icon'  => 'dashicons-admin-plugins',
        'group' => 'settings',
    );
    return $tabs;
} );

Utility filters

`bp_suggestions_compose_message_url`

Override the pre-filled URL used for the “Send Message” button in suggestion templates.

apply_filters( 'bp_suggestions_compose_message_url', $message_url );

Default is {logged-in-user-domain}/messages/compose/?r=.

`bp_suggestions_user_status_html`

Override the HTML rendered for online status indicators.

apply_filters( 'bp_suggestions_user_status_html', $status_html, $user_id );

Parameter	Type	Description
`$status_html`	`string`	Default: `<span class="member-status online"></span>`

`bffs_force_public_enqueue`

Return true to force the plugin’s CSS/JS to load on every page, overriding the default conditional loading.

apply_filters( 'bffs_force_public_enqueue', false );

Default is false. Only change this if your theme loads suggestion widgets in unexpected locations.

`bffs_license_api_sslverify`

Control SSL certificate verification for license API requests.

apply_filters( 'bffs_license_api_sslverify', true );

Set to false only in local development environments where self-signed certificates are in use.