Install Buying Buddy in React Applications

This 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: Next.js, 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 and AI website builders. A manual <script>-based method is also available as a fallback for the rare project that cannot add an npm dependency.

Using an AI Website Builder (HighLevel AI Studio & others)

If your site is built with an AI website builder such as HighLevel AI Studio — or a similar tool like Lovable, Bolt, or v0 — you are working in a standard React project (typically Vite + React + TypeScript). Use Method 1, the @buyingbuddy/react package: install it, wrap your app in the provider, and add widgets as components. Do not use the manual script method — it is unreliable in AI builders (see below).

Because these builders are driven by an AI assistant, the fastest way to set everything up is to hand that assistant a ready-made prompt. Your Buying Buddy dashboard generates this prompt pre-filled with your account's activation key and foundation-page paths, so the AI has everything it needs to install the package, create your Results and Details pages, add the disclaimer, and offer a search form.

Setting up by hand, or using another React framework? Continue with the step-by-step instructions below.

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)

1

Install the Package & Get Your Activation Key

Add the dependency and find your activation key

Inside an existing React project, install the package and make sure React is present:

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

Starting from scratch? This gets you from nothing to a running page with Vite:

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

Finding Your Activation Key

You can locate your activation key in several places:

• Welcome email: If you just created an account, check the welcome email we sent you—your activation key is included there.
• Widgets page: Your activation key is displayed at the bottom of the Menu Widgets dropdown menu in your Buying Buddy dashboard.
• Authorized Websites page: Navigate to Menu Widgets > Authorized Websites to find your key at the top of the page.
• Plugin Installation page: Go to Installation and Setup — Menu Widgets > Installation and Setup — where it is shown with your plugin install details.

Copy that value — you will pass it to the provider as the activationKey prop in the next step (Step 2).

// 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>
)

// app/providers.tsx
"use client"

import { BuyingBuddyProvider } from "@buyingbuddy/react"

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

// app/layout.tsx
import Providers from "./providers"

export default function RootLayout({ children }) {
    return (
        <html lang="en">
            <body>
                <Providers>{children}</Providers>
            </body>
        </html>
    )
}

// pages/_app.tsx
import { BuyingBuddyProvider } from "@buyingbuddy/react"

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

// 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

Required Results and Details routes

Important: Buying Buddy needs two dedicated "Foundation Pages" — one for search results, one for property details. The main page content of each foundation page must contain only one widget (the results or details 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 two routes in your application, each rendering a single widget. The example uses Next.js App Router conventions, but 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="SearchResults" />
}

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

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

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
4. Update them if your routes use different paths

Important: Do not add a SearchForm or QuickSearch widget to the Results or Details routes — 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 with a fixed height
<BuyingBuddyWidget type="InteractiveMap" style={{ height: "600px" }} />

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.

<!-- 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>

// app/layout.tsx
import Script from "next/script"

export default function RootLayout({ children }) {
    return (
        <html lang="en">
            <head>
                <Script
                    src="https://www.mbb2.com/.../YOUR_BUYING_BUDDY_PLUGIN.js"
                    strategy="beforeInteractive"
                />
            </head>
            <body>{children}</body>
        </html>
    )
}

// pages/_document.tsx
import { Html, Head, Main, NextScript } from "next/document"

export default function Document() {
    return (
        <Html lang="en">
            <Head>
                <script src="https://www.mbb2.com/.../YOUR_BUYING_BUDDY_PLUGIN.js" />
            </Head>
            <body>
                <Main />
                <NextScript />
            </body>
        </Html>
    )
}

// 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, style, 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%", ...style }}
            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="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.

"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.

Hydration errors in Next.js

A hydration mismatch can occur because the widget DOM is created client-side and isn't present in the server-rendered HTML. The package's wrapper already sets suppressHydrationWarning on its container. If you wrote your own wrapper (manual method), add suppressHydrationWarning to the wrapper <div> as shown in Method 2, Step 3.

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, _document, 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 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.