Install Buying Buddy in React Applications

This REACT guide covers how to add Buying Buddy widgets to React-based applications and React-powered website builders. It is intended for developers comfortable with React, JSX, and modern JavaScript tooling.

Applies to: Gatsby, Remix, Vite + React, Create React App, and React-based site builders. For Framer, follow the dedicated Install Buying Buddy on Framer guide, which uses a ready-made single-file component.

How to Install

The recommended way to add Buying Buddy to a React project is the official package, @buyingbuddy/react. It is built specifically for React and handles the widget lifecycle correctly, including in single-page apps. A manual <script>-based method is also available as a fallback for the rare project that cannot add an npm dependency.

Important Notes Before You Begin

How Buying Buddy Widgets Work in React

Buying Buddy widgets are implemented as HTML Custom Elements (<bb-widget>), registered by the plugin runtime. They use the standard Custom Elements lifecycle - specifically connectedCallback - so a widget initializes the moment its element is attached to the DOM, reading its attributes (data-type, data-filter, and so on) at that point.

In plain HTML this is seamless: the element is parsed with its attributes already present. In React, prior to React 19, unknown props on a custom element could be dropped or set as DOM properties instead of HTML attributes - so a widget could initialize without its configuration and render empty. The reliable pattern across all React versions is to create the <bb-widget> element imperatively and set its attributes with setAttribute before attaching it to the DOM.

Method 1 - The @buyingbuddy/react Package (Recommended)

npm install @buyingbuddy/react
npm install react react-dom

npm create vite@latest my-site -- --template react
cd my-site
npm install
npm install @buyingbuddy/react
npm run dev

// src/main.jsx
import { StrictMode } from "react"
import { createRoot } from "react-dom/client"
import { BuyingBuddyProvider } from "@buyingbuddy/react"
import App from "./App.jsx"

createRoot(document.getElementById("root")).render(
    <StrictMode>
        <BuyingBuddyProvider activationKey="your-activation-key">
            <App />
        </BuyingBuddyProvider>
    </StrictMode>
)

// gatsby-browser.js
import React from "react"
import { BuyingBuddyProvider } from "@buyingbuddy/react"

export const wrapRootElement = ({ element }) => (
    <BuyingBuddyProvider activationKey="your-activation-key">
        {element}
    </BuyingBuddyProvider>
)

// app/root.tsx
import { Outlet } from "@remix-run/react"
import { BuyingBuddyProvider } from "@buyingbuddy/react"

export default function App() {
    return (
        <BuyingBuddyProvider activationKey="your-activation-key">
            <Outlet />
        </BuyingBuddyProvider>
    )
}

3

Create Foundation Pages

Results, Details, Market Report, and Communities routes

Important: Buying Buddy uses four dedicated "Foundation Pages" - Search Results, Property Details, Market Report, and Communities Hub. The main page content of each must contain only one Buying Buddy widget (its results, details, market report, or communities widget). It is fine to also have the Disclaimer widget in the page footer and login/account widgets in the header. For a full explanation, see Understanding Foundation Pages.

Create four routes in your application, each rendering a single widget. The pattern is the same for any framework - the import lives wherever your route components live.

// Results route  ->  /listing-results
import { BuyingBuddyWidget } from "@buyingbuddy/react"

export default function ResultsPage() {
    return <BuyingBuddyWidget type="ListingResults" />
}

// Details route  ->  /listing-details
import { BuyingBuddyWidget } from "@buyingbuddy/react"

export default function DetailsPage() {
    return <BuyingBuddyWidget type="SearchDetails" />
}

// Market Report route  ->  /market-area-report
import { BuyingBuddyWidget } from "@buyingbuddy/react"

export default function MarketReportPage() {
    return <BuyingBuddyWidget type="MarketReport" />
}

// Communities route  ->  /featured-communities
import { BuyingBuddyWidget } from "@buyingbuddy/react"

export default function CommunitiesPage() {
    return <BuyingBuddyWidget type="Communities" />
}

Note: SearchResults and ListingResults are interchangeable - both render the same results widget. Likewise SearchDetails and ListingDetails.

Confirm Foundation Page Settings:

1. Return to your Buying Buddy dashboard
2. Go to Menu Widgets > Installation and Setup > Foundation Pages tab
3. Verify the page addresses match your route paths:
   - Results: /listing-results
   - Details: /listing-details
   - Market Report: /market-area-report
   - Communities Hub: /featured-communities
4. Update them if your routes use different paths

Important: Do not add a SearchForm or QuickSearch widget to any foundation route (Results, Details, Market Report, or Communities) - this will break widget behavior.

// Footer.jsx
import { BuyingBuddyWidget } from "@buyingbuddy/react"

export default function Footer() {
    return (
        <footer>
            {/* ...your footer content... */}
            <BuyingBuddyWidget type="Disclaimer" />
        </footer>
    )
}

import { BuyingBuddyWidget } from "@buyingbuddy/react"

// Standard search form
<BuyingBuddyWidget type="SearchForm" />

// Compact one-line quick search
<BuyingBuddyWidget type="QuickSearch" filter="formType:simple1" />

// Featured gallery - 12 of the account's own listings
<BuyingBuddyWidget type="FeaturedGallery" filter="limit:12" />

// Interactive map
<BuyingBuddyWidget type="InteractiveMap" />

Method 2 - Manual Install (Script + bb-widget) - Fallback Only

If you do use this method, you will add your personalized plugin script to the page yourself, then place <bb-widget> elements. The overall sequence - plugin, foundation pages, disclaimer, search form, test - is the same as Method 1.

For the manual method, set your website type to HTML so the dashboard generates the correct personalized plugin script (which already includes your activation key).

1. In the top menu, go to Website Options
   Menu Widgets > Website Options
2. Select the Website Settings tab, and in the header click the link to change the website type to HTML
3. Open the Installation and Setup page - it will now show your personalized JavaScript plugin (including your activation key) along with the matching instructions
4. Copy the plugin JavaScript from the Add Plugin tab

<!-- index.html -->
<head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My App</title>
    <!-- Paste your personalized Buying Buddy plugin script here -->
    <script src="https://www.mbb2.com/.../YOUR_BUYING_BUDDY_PLUGIN.js"></script>
</head>

// gatsby-ssr.js
import React from "react"

export const onRenderBody = ({ setHeadComponents }) => {
    setHeadComponents([
        <script
            key="buying-buddy-plugin"
            src="https://www.mbb2.com/.../YOUR_BUYING_BUDDY_PLUGIN.js"
        />,
    ])
}

// app/root.tsx
export function Layout({ children }) {
    return (
        <html lang="en">
            <head>
                <Meta />
                <Links />
                <script src="https://www.mbb2.com/.../YOUR_BUYING_BUDDY_PLUGIN.js" />
            </head>
            <body>
                {children}
                <ScrollRestoration />
                <Scripts />
            </body>
        </html>
    )
}

<bb-widget data-type="SearchForm"></bb-widget>
<bb-widget data-type="QuickSearch" data-filter="formType:simple1"></bb-widget>

// BuyingBuddyWidget.jsx
import { useEffect, useRef } from "react"

export default function BuyingBuddyWidget({ widgetType, filter, className }) {
    const containerRef = useRef(null)

    useEffect(() => {
        const container = containerRef.current
        if (!container) return

        // Clear any existing widget (handles re-renders and filter changes)
        container.innerHTML = ""

        // Create the element imperatively - attributes are set before
        // DOM attachment, so connectedCallback sees them immediately.
        const widget = document.createElement("bb-widget")
        widget.setAttribute("data-type", widgetType)
        if (filter) widget.setAttribute("data-filter", filter)

        container.appendChild(widget)

        return () => {
            container.innerHTML = ""
        }
    }, [widgetType, filter])

    return (
        <div
            ref={containerRef}
            style={{ width: "100%" }}
            className={className}
            suppressHydrationWarning
        />
    )
}

import BuyingBuddyWidget from "./BuyingBuddyWidget"

<BuyingBuddyWidget widgetType="SearchForm" />
<BuyingBuddyWidget widgetType="FeaturedList" filter="city:denver+price_min:300000" />

<bb-widget data-type="ListingResults"></bb-widget>
<bb-widget data-type="SearchDetails"></bb-widget>
<bb-widget data-type="MarketReport"></bb-widget>
<bb-widget data-type="Communities"></bb-widget>
<bb-widget data-type="Disclaimer"></bb-widget>
<bb-widget data-type="SearchForm"></bb-widget>

Widget Props Reference

When using the @buyingbuddy/react package, <BuyingBuddyWidget> accepts the following props. Only type is required.

The provider, <BuyingBuddyProvider>, accepts activationKey (required) and an optional fallback rendered while the runtime loads.

Available Widget Types for REACT

The table below lists the Buying Buddy widgets in their React form. Pass the value shown to the type prop of <BuyingBuddyWidget> (inside your <BuyingBuddyProvider>). This mirrors the master Published IDX Widget Set - refer to that article for the definitive list.

Enable Property Sharing

Set up social media sharing so shared property links show the correct listing photo and details.

To allow visitors to share properties from your website on Facebook and other social media platforms with the correct listing photos and details, you'll need to set up a "bb" subdomain for your domain.

Next Step:

Note: Your Buying Buddy dashboard has customized instructions for your domain in the Installation and Setup section (Social Share Settings tab) of your Buying Buddy account.Widgets - Installation and Setup : Social Share tab
Menu Widgets > Plugin Installation and Settings > Social Share tab

Troubleshooting

Widgets render an empty container

The most likely cause is that the runtime has not registered the <bb-widget> custom element before the widget mounts. With the package, make sure your widget is inside <BuyingBuddyProvider>. With the manual method, confirm the plugin script is in the <head> and not deferred. In the browser console, run customElements.get("bb-widget") - if it returns undefined, the runtime has not registered.

Widgets, map, or listing photos blocked by a Content-Security-Policy

If your site sets a Content-Security-Policy, the browser blocks Buying Buddy's resources unless each host is explicitly allowed. Because the provider cannot see why a blocked script failed, this often surfaces as a generic "Failed to load BuyingBuddy script" error - or the map and listing photos simply do not render, with no obvious error. Note that React does not add a CSP by default, so if you have not configured one, this is not your issue.

To confirm, open your browser's developer console. CSP violations are logged there, each naming the blocked host and the directive that blocked it. Add each blocked host to the matching directive:

• script-src and connect-src - the Buying Buddy runtime and its search / property data API
• style-src and font-src - the per-account widget theme stylesheet and its fonts
• img-src - widget media, plus your MLS's listing-photo host (this host is specific to your MLS - read the exact value from the console)
• Interactive Map: the map host in script-src, connect-src, and img-src, plus worker-src 'self' blob: (the map runs in a blob-URL web worker and fails silently without it)

The exact hostnames always appear in the console as blocked requests - use those rather than guessing, since some hosts (your MLS's listing-photo host in particular) vary by account. If you would like a known-good example CSP as a starting point, contact support through your Buying Buddy dashboard.

"Invalid activation key or unauthorized domain"

The package provider shows this built-in error when the runtime loads but the account/domain check fails. Verify your activationKey is correct and that the current domain is registered to your account. For development, contact support via the Help Desk to authorize your sandbox or staging domain.

"Sorry, this domain is not authorized"

The runtime is loading but the domain is not registered in your Buying Buddy account. For production, verify the domain in Menu Widgets > Installation and Setup. For development domains (a sandbox or staging domain), contact support to authorize them.

Widget loses state when a prop changes

Changing type or filter tears down and rebuilds the underlying widget, which loses in-widget state such as map position, scroll, or form input. This is expected. Avoid changing those props unnecessarily; if parent re-renders are the cause, memoize the props or wrap the widget in React.memo.

Plugin loads more than once

Loading the runtime more than once causes unpredictable behavior. With the package, use a single provider per page. With the manual method, ensure the script appears only in your root layout or index.html - never inside page components. Search your codebase for the plugin URL to confirm there is only one instance.

"SQL Error" on the Details page during testing

Viewing the Details route directly, without a property reference, can show a temporary error. This is normal during testing and is never seen by visitors who arrive from a results listing.

Next Steps

Your React site is ready for advanced Buying Buddy features. Consider adding:

• Featured listing galleries for your own properties
• Neighborhood / community pages
• Lead capture forms connected to the Buying Buddy CRM
• An interactive map search experience
• Custom styling with Widget Themes

Related Resources

• Install Buying Buddy on Next.js - dedicated guide for Next.js (App Router and Pages Router)
• Install Buying Buddy on Framer - dedicated guide for Framer
• Understanding Foundation Pages
• Filter Parameters Reference
• Widget Overview
• Troubleshooting JavaScript Plugin Installation Issues

Need additional help? Contact our support team through your Buying Buddy dashboard.