Quick Setup

Quick Setup

This guide gets the plugin producing suggestion cards on your site in about five minutes. For more control over each setting, see the Settings section.

Step 1 - Enable profile matching

1. Go to BuddyPress > Friend & Follow Suggestion.
2. On the General tab, turn on the Enable Profile Matching toggle.

The Weighted Field Matching table and the Universal Match Score field appear once you enable matching.

Step 2 - Configure matching fields

The matching engine compares xProfile field values between members. You need to tell it which fields to use and how much weight each carries.

1. Click Add Field to add your first field row.
2. Use the dropdown to pick an xProfile field. Fields that work best for matching are choice-based: checkboxes, select boxes, radio buttons, and multi-selects. Text fields (text box, textarea) produce much lower quality matches because exact string comparison rarely succeeds.
3. Set a Weight (%) for the field. Each weight represents how much that field contributes to the overall score.
4. Optionally check Required on a field (see below for what this does).
5. Add more fields and click Save Matching Settings.

Good field choices for a typical community:

Field type	Example	Recommended weight
Checkbox (multi-value)	Interests, Hobbies	25–35%
Multi-select	Skills, Genres	20–30%
Select box (single)	Country, Industry	15–25%
Radio	Age group, Experience level	15–25%

How scores are calculated

For each configured field, the engine awards the full field weight when the two members’ values overlap (for multi-value fields, any shared option counts). For single-value fields such as a select box, the two values must match exactly.

After scoring all fields, the engine adds the Universal Match Score (see below) to produce the final percentage shown on suggestion cards. The result is capped at 100.

When total weights exceed 100%: if your field weights add up to more than 100, the engine rescales the field contributions proportionally so the final score stays meaningful. The admin panel shows a live “Total weight” indicator and flags when normalization will apply.

Universal Match Score

The Universal Match Score field (under the field table) sets a flat score that is added to every pair’s result before field matching contributes. It defaults to 20% — that value is written to the database when the plugin first activates, so the engine is already using 20 before you visit the settings page.

Set this to a small positive number (the admin panel recommends 15–25%) if you want members with no profile overlap to still appear as suggestions at a low score. Leave it at 0 if you want members with nothing in common to score 0 and be filtered out by the widget’s minimum threshold.

The Required checkbox

Checking Required on a field means the pair must share a value on that field. If they do not match, or if either member has left that field empty, the engine assigns the pair a final score of 0, regardless of how well they matched on other fields. A score of 0 falls below every widget threshold, so the pair will not appear as a suggestion.

Use Required for hard compatibility criteria such as language, location, or membership tier where a mismatch makes the suggestion irrelevant.

Step 3 - Place a suggestions widget

Go to Appearance > Widgets (or use the block-based widget editor).

Two widgets are available:

• BuddyPress Friend & Follow Suggestion - a standard list or grid of cards.
• BuddyPress Friend & Follow Swiper - a swipeable card deck (mobile-friendly swipe-left-to-dismiss, swipe-right-to-like).

Drag the widget you want into a sidebar. Configure the number of members to display and, for the standard widget, the layout style (cards, list, or horizontal). Save.

Step 4 - Verify on the frontend

Log in as a member and visit a page where the widget is displayed. You should see suggestion cards with profile photos, member names, match percentages, and Connect / Follow action buttons.

If no cards appear:

• Check that the current user has filled in the xProfile fields you configured. The engine can only score fields that have values.
• Check that there are other members on the site with non-empty matching fields.
• Make sure the Enable Profile Matching toggle is on.
• If all fields show 0% matches, check that the Universal Match Score is set to a value above 0 or that members have overlapping field values.

Step 5 - Optional: Add shortcodes to pages

You can embed suggestion lists on any page using shortcodes. The most common ones:

[bp_friend_suggestions]
[bp_follow_suggestions]
[bp_top_matches]

Add these to a page’s content using the block editor’s Shortcode block. See Shortcodes Reference for the full list and attributes.

What to configure next

• Display & Appearance - choose layout, card size, colors, and whether to show match scores in the member directory.
• Notifications - set up email digests so members receive weekly or daily suggestion summaries.