@bagisto-native/react

@bagisto-native/react provides React wrappers for the Web Components included in @bagisto-native/core, making it easy to integrate Bagisto Native functionality into React.js and Next.js applications.

It is designed to work smoothly with Open Source Headless eCommerce and any React.js or Next.js setup, making it easy to connect a headless storefront with native mobile apps.

This module is intended to be used together with @bagisto-native/core.

Note: To create Bagisto Headless Commerce, use the following command:

npx -y @bagisto-headless/create your-storefront

📦 Installation

Install the module via npm:

npm install @bagisto-native/react

Note: Ensure that @bagisto-native/core is also installed and the bundle.js is included in your project.

🌐 Components

@bagisto-native/react provides React wrappers for the following Web Components:

| Component | Description | | -------------------- | ----------------------------------------------------------------- | | DynamicButton | Handles native buttons for cart, share, barcode, and image search | | HotwireToast | Trigger native toast messages | | HotwireSearch | Trigger native search events | | HotwireLocation | Auto-fill checkout address using native location | | HotwireHistorySync | Send current page URL and tab-title to native apps | | HotwireThemeMode | Send current theme mode (light/dark) |

All components should be used inside client components in Next.js ('use client') since they interact with the browser.

⚡ Usage Examples

Hotwire Toast

'use client';
import dynamic from 'next/dynamic';

const HotwireToast = dynamic(
  () => import('@bagisto-native/react').then(mod => mod.HotwireToast),
  { ssr: false }
);

export default function AppToast() {
  return <HotwireToast />;
}

Trigger a toast from @bagisto-native/core:

import { triggerHotwireNativeToast } from '@bagisto-native/core';

triggerHotwireNativeToast('Hello World!');

Hotwire History Sync

'use client';
import dynamic from 'next/dynamic';

const HotwireHistorySync = dynamic(
  () => import('@bagisto-native/react').then(mod => mod.HotwireHistorySync),
  { ssr: false }
);

export default function AppHistorySync() {
  return <HotwireHistorySync />;
}

Trigger history sync from @bagisto-native/core:

import { useEffect } from 'react';
import { usePathname, useSearchParams } from 'next/navigation';
import { triggerHistorySyncEvent } from '@bagisto-native/core';

export default function HistorySync() {
  const pathname = usePathname();
  const searchParams = useSearchParams();

   useEffect(() => {
    const url = new URL(`${window.location.origin}${pathname}${searchParams.toString() ? `?${searchParams.toString()}` : ""}`);
    const tabTitle = document?.title || "";
    triggerHistorySyncEvent(url, tabTitle);
  }, [pathname, searchParams]);

  return null;
}

Hotwire Theme Mode

'use client';
import dynamic from 'next/dynamic';

const HotwireThemeMode = dynamic(
  () => import('@bagisto-native/react').then(mod => mod.HotwireThemeMode),
  { ssr: false }
);

export default function AppThemeMode() {
  return <HotwireThemeMode />;
}

Send theme mode:

import { triggerThemeModeEvent } from '@bagisto-native/core';

triggerThemeModeEvent('light'); // 'light' or 'dark'

Hotwire Search

'use client';
import dynamic from 'next/dynamic';

const HotwireSearch = dynamic(
  () => import('@bagisto-native/react').then(mod => mod.HotwireSearch),
  { ssr: false }
);

export default function AppSearch() {
  return <HotwireSearch />;
}

Listen to search events:

import { useEffect } from 'react';
import { useRouter } from 'next/navigation';

export default function TurboSearchRouterBridge() {
  const router = useRouter();

  useEffect(() => {
    // Listen for a custom event from Turbo.
    const handleTurboSearch = (e: Event) => {
      const customEvent = e as CustomEvent<{ query?: string; code?: string }>;
      const query = customEvent.detail.query || customEvent.detail.code;
      if (!query) return;
      router.push(`/search?q=${encodeURIComponent(query)}`);
    };

    window.addEventListener("turbo:next-search", handleTurboSearch);

    return () => {
      window.removeEventListener("turbo:next-search", handleTurboSearch);
    };
  }, [router]);

  return null; 
}

Hotwire Location

'use client';
import dynamic from 'next/dynamic';

const HotwireLocation = dynamic(
  () => import('@bagisto-native/react').then(mod => mod.HotwireLocation),
  { ssr: false }
);

export default function AppLocation(props: { fieldNames: { address: string[]; city: string[]; postCode: string[] } }) {
  return (
    <HotwireLocation fieldNames={props.fieldNames} style={{ display: 'none' }}>
      Hotwire Location
    </HotwireLocation>
  );
}

Dynamic Button

'use client';
import dynamic from 'next/dynamic';

const DynamicButton = dynamic(
  () => import('@bagisto-native/react').then(mod => mod.DynamicButton),
  { ssr: false }
);

export default function AppDynamicButton(props: { dataPageType?: string }) {
  return (
    <>
      <DynamicButton pageType={props.dataPageType || 'home'} style={{ display: 'none' }} />
    </>
  );
}

Use pageType='home' on homepage, pageType='product' on product pages and pageType='empty' for hiding the previous page dynamic button icons.

On both the home page and product page variants, the dynamic button component also shows the cart icon in the native app area. When we click on the cart icon, it emits the turbo:next-cart-modal event. You can open the cart modal or route to the cart page as per your requirement by listening to this event.

If you want to open the cart modal and also include the native modal close button on the screen, you can use the following configuration of DynamicButton:

<DynamicButton
  modalOpenEvent={true}
  style={{ display: 'none' }}
>
</DynamicButton>

<DynamicButton
  modalDismissEvent={true}
  style={{ display: 'none' }}
>
</DynamicButton>

Now, you also have to send the event to the native side of the application when you open the modal, and also send the event when you close the modal via external sources.

For sending the modal open event, use the following method:

import { triggerDynamicButtonModalOpenEvent } from '@bagisto-native/core';

triggerDynamicButtonModalOpenEvent();

For sending the modal dismiss event, use the following method:

import { triggerDynamicButtonModalDismissEvent } from '@bagisto-native/core';

triggerDynamicButtonModalDismissEvent();

However, without the native cart modal close icon, you can handle the cart modal or any other modal by only listening to the turbo:next-cart-modal event.

For using the cart count variant, you need to add the following configuration of DynamicButton:

<DynamicButton cartCountEvent={true} style={{ display: 'none' }} />

Now, whenever the cart count changes, you also need to notify the native app. For this, you can use the following method from @bagisto-native/core:

import { triggerCartCountValue } from '@bagisto-native/core';

triggerCartCountValue(5);

Dynamic Button Home Page Variant

It basically shows three icons on the home page. The first one is for the Image Search feature, the second one is for the Barcode/QR code feature, and the third one is for the Cart and cart count feature.

When you click on the Image Search icon or the Barcode/QR code icon, the corresponding native component opens and sends the processed data via the turbo:next-search event. You can listen to this event and handle the search process.

useEffect(() => {
  // Listen for a custom event from Turbo.
  const handleTurboSearch = (e: Event) => {
    const customEvent = e as CustomEvent<{ query?: string; code?: string }>;
    const query = customEvent.detail.query || customEvent.detail.code;
    if (!query) return;
    router.push(`/search?q=${encodeURIComponent(query)}`);
  };

  window.addEventListener("turbo:next-search", handleTurboSearch);

  return () => {
    window.removeEventListener("turbo:next-search", handleTurboSearch);
  };
}, [router]);

Dynamic Button Product Page Variant

In this variant, the dynamic button component shows the product share icon and cart icon in the application’s native area. The cart icon works the same as in the home page variant of the dynamic button component. When you click on the product share icon, it will open the native share modal, and you can handle the share process.

Dynamic Button Emtpy Variant

When we use the home or product variant of the dynamic button and then navigate to the auth pages, the previous-page icon remains visible. To hide this icon on the auth pages, use the empty variant of the dynamic button.

<DynamicButton pageType='empty' style={{ display: 'none' }} />

📋 Requirements

• Node.js >= 18
• React >= 18 / Next.js >= 15
• @bagisto-native/core must be installed and bundle.js included

🆘 Support

Open an issue or discussion in the repository if you need help.

📄 License

MIT License