Shortcode Reference

The plugin provides eight shortcodes. You can drop any of them into a page, post, or widget text area to display suggestion data wherever you need it. All shortcodes require the visitor to be logged in unless stated otherwise.

Prerequisite: The matching engine must be turned on at WB Plugins > BP Friend & Follow > General > Enable Profile Matching. All eight shortcodes silently output nothing when that toggle is off.

[bp_friend_suggestions]

Shows a list of members the current user has not yet befriended, ranked by profile compatibility.

Attributes

Attribute	Default	Accepted values
`limit`	`5`	Any positive integer
`layout`	(from settings)	`cards`, `list`, `grid`

Example usage

[bp_friend_suggestions]
[bp_friend_suggestions limit="10"]
[bp_friend_suggestions limit="5" layout="list"]

Output - member cards or list rows, each containing:

Avatar (when “Show Avatars” is on in Display settings)
Member name linking to their BuddyPress profile
Compatibility percentage (when “Show Match Percentage” is on)
Add Friend button (when the BuddyPress Friends component is active)
Follow button (when a follow component is active - see [bp_follow_suggestions] below)
Dismiss button (when “Not Interested” is on in UX settings)

Empty state - when the engine finds no candidates: “No new friend suggestions yet” with guidance to fill out the profile and join groups.

Logged-out - returns: Please log in to see friend suggestions.

[bp_follow_suggestions]

Shows members the current user does not already follow, ranked by the same profile compatibility score. Requires the BuddyPress Follow component or BuddyBoss platform follow feature to be active. On sites where neither is installed the candidate pool falls back to the same members as [bp_friend_suggestions].

Attributes

Attribute	Default	Accepted values
`limit`	`5`	Any positive integer
`layout`	(from settings)	`cards`, `list`, `grid`

Example usage

[bp_follow_suggestions limit="8"]
[bp_follow_suggestions layout="cards"]

Output - same card structure as [bp_friend_suggestions].

Empty state - “No follow suggestions yet” with guidance to fill in interests.

Logged-out - returns: Please log in to see follow suggestions.

[bp_match_percentage]

Returns the raw compatibility percentage between the current user and a specific member. Outputs an inline <span> only, so you can embed it inside a sentence.

Attributes

Attribute	Default	Required
`user_id`	-	Yes

Example usage

You and Jane are [bp_match_percentage user_id="123"] compatible.

Output

<span class="bffs-match-score">87%</span>

Empty / edge cases - returns an empty string when: the user is logged out; user_id is missing or zero; or the match score is zero.

[bp_top_matches]

Shows the current user’s highest-scoring members across the whole community, regardless of whether they are already friends or follows. No relationship filter is applied, making this distinct from [bp_friend_suggestions] and [bp_follow_suggestions]. Results are always sorted with the highest compatibility score first.

Attributes

Attribute	Default	Accepted values
`limit`	`10`	Any positive integer
`layout`	(from settings)	`cards`, `list`, `grid`

Example usage

[bp_top_matches]
[bp_top_matches limit="5" layout="cards"]

Output - same card structure as [bp_friend_suggestions].

Empty state - “No suggestions available right now” with guidance to update the profile.

Logged-out - returns: Please log in to see your top matches.

[bp_common_interests]

Lists the BuddyPress xProfile field values that both the current user and a target member share. Requires user_id to identify the comparison target.

Attributes

Attribute	Default	Required
`user_id`	-	Yes

Example usage

[bp_common_interests user_id="123"]

Output

<div class="bffs-common-interests">
    <h4>Common Interests</h4>
    <ul>
        <li><strong>Hobbies:</strong> Photography, Hiking</li>
        <li><strong>Music Genres:</strong> Rock, Jazz</li>
    </ul>
</div>

Empty state - returns No common interests found.

Logged-out - returns an empty string.

Note - the output reflects whichever xProfile fields you configured for matching in Settings > General. Fields not included in match data are not compared.

[bp_mutual_friends]

Lists friends that both the current user and a target member share. Requires the BuddyPress Friends component to be active. If the Friends component is inactive the shortcode returns an empty string.

Attributes

Attribute	Default	Required
`user_id`	-	Yes
`limit`	`5`	No

Example usage

[bp_mutual_friends user_id="123"]
[bp_mutual_friends user_id="456" limit="10"]

Output

<div class="bffs-mutual-friends">
    <h4>Mutual Friends (7)</h4>
    <ul class="bffs-mutual-friends-list">
        <li><a href="/members/jane/">Jane Smith</a></li>
        <li><a href="/members/john/">John Doe</a></li>
    </ul>
</div>

The heading always shows the total mutual friend count even when limit trims the list.

Empty state - returns No mutual friends.

Logged-out - returns an empty string.

[bp_suggestions_count]

Returns the number of suggestion candidates available for the current user. Use it inline inside text or for a badge count. Accepts an optional minimum score threshold.

Attributes

Attribute	Default	Description
`threshold`	`0`	Only count members at or above this percentage

Example usage

You have [bp_suggestions_count] friend suggestions waiting.
You have [bp_suggestions_count threshold="75"] high-quality matches.

Output (logged in)

<span class="bffs-suggestions-count">12</span>

Logged-out - returns the bare string 0 with no <span> wrapper.

Note - this shortcode calls the full suggestion engine (up to 100 candidates) to produce the count. On large communities with caching disabled, use a reasonable refresh interval in UX settings to avoid repeated heavy queries.

[bp_match_breakdown]

Renders a table showing each configured profile field, the current user’s value, the target member’s value, the field’s weight in the overall score, and whether the values matched. Useful for “why did we match?” or comparison pages.

Attributes

Attribute	Default	Required
`user_id`	-	Yes

Example usage

[bp_match_breakdown user_id="123"]

Output

<div class="bffs-match-breakdown">
    <h4>Compatibility Breakdown</h4>
    <table class="bffs-breakdown-table">
        <thead>
            <tr>
                <th>Field</th>
                <th>Your Value</th>
                <th>Their Value</th>
                <th>Weight</th>
                <th>Match</th>
            </tr>
        </thead>
        <tbody>
            <tr class="match-yes">
                <td>Age Range</td>
                <td>25-35</td>
                <td>30-40</td>
                <td>25%</td>
                <td>&#10003;</td>
            </tr>
            <tr class="match-no">
                <td>Location</td>
                <td>New York</td>
                <td>California</td>
                <td>20%</td>
                <td>&#10007;</td>
            </tr>
        </tbody>
    </table>
</div>

Table rows carry one of two CSS classes: match-yes for fields that matched, match-no for fields that did not.

Empty state - returns No match data available.

Logged-out - returns an empty string.

Layout values

The layout attribute on [bp_friend_suggestions], [bp_follow_suggestions], and [bp_top_matches] controls how cards are rendered. The shortcode adds a modifier class to the container:

`layout` value	Container class	Renders as
`cards`	`bffs-layout-cards`	Responsive multi-column grid
`list`	`bffs-layout-list`	Single-column vertical list
`grid`	`bffs-layout-grid`	Fixed-column grid

When no layout attribute is supplied the shortcode reads the value from Settings > Display & Appearance > Layout Style.

CSS customization

The plugin emits CSS custom properties in <style id="bffs-runtime-tokens"> on every frontend page load. You can override them in your theme stylesheet.

:root {
    --bffs-primary-color: #007AFF;   /* Set in Settings > Display > Color Scheme */
    --bffs-success-color: #34C759;
    --bffs-text-color: #1d1d1f;
    --bffs-per-row: 3;               /* Set in Settings > Display > Suggestions Per Row */
    --bffs-avatar-size: 100px;       /* Set in Settings > Display > Avatar Size */
}

Named CSS classes you can target:

Class	Applied to
`.bffs-suggestions-container`	Outer wrapper for all suggestion lists
`.bffs-card`	Individual member card
`.bffs-card--high-match`	Card where score meets the “High Match Threshold”
`.bffs-card--score-high`	Score 60-100
`.bffs-card--score-med`	Score 30-59
`.bffs-card--score-low`	Score 1-29
`.bffs-card-avatar`	Avatar link element
`.bffs-card-body`	Text and action area
`.bffs-match-score`	Compatibility percentage element
`.bffs-common-interests`	Common interests container
`.bffs-mutual-friends`	Mutual friends container
`.bffs-match-breakdown`	Breakdown table container
`.bffs-breakdown-table`	The `<table>` inside the breakdown
`.match-yes`	Breakdown table row where values matched
`.match-no`	Breakdown table row where values did not match

Common patterns

Suggestion sidebar (3 cards)

[bp_friend_suggestions limit="3" layout="list"]

Top matches page

[bp_top_matches limit="20" layout="cards"]

Compatibility detail between two members - place these on a page that receives a ?user_id= query parameter and use that value:

Match score: [bp_match_percentage user_id="123"]

[bp_common_interests user_id="123"]
[bp_mutual_friends user_id="123" limit="10"]
[bp_match_breakdown user_id="123"]

Notification badge in nav menu - add this inside a custom menu item label:

Suggestions <span class="badge">[bp_suggestions_count threshold="50"]</span>

Troubleshooting

Shortcode renders nothing

Confirm the visitor is logged in.
Go to WB Plugins > BP Friend & Follow > General and check that “Enable Profile Matching” is on.
Check that at least one xProfile field is configured for matching in the General settings.

Percentage shows 0 or no cards appear

The user has not filled in any matchable xProfile fields.
No other members share values on the configured fields.
The minimum match threshold (set per widget or in advanced settings) may be set too high.

[bp_follow_suggestions] shows the same people as [bp_friend_suggestions]

This happens on sites without the BuddyPress Follow component or BuddyBoss follow feature active. The pool falls back automatically.

[bp_mutual_friends] shows nothing

Confirm the BuddyPress Friends component is active in BuddyPress > Components.

[bp_match_breakdown] table is empty

The user_id attribute is missing or zero.
The BFFS_UX class is not available (check the plugin is fully activated).