Skip to main content

React & Vue Integration

While our SDK works well in any environment, React and Vue developers can achieve the best results by directly integrating GLOW's lower-level functions into custom components. This guide provides React and Vue-specific examples that you can further customize, with additional tips for compatibility with single page applications (SPAs).

Note

The component examples in this guide use generic HTML elements like <button>, and don't include any styles. It's assumed you will swap in your own components, and design everything to fit your site.

While GLOW can be integrated with any version of any UI library, the examples in this guide are written for:

  • React: Compatible with all modern versions of React (16.8 and above).
  • Vue: Written for Vue 3 using the Single-File Component (SFC) format.
Troubleshooting

Something not working? Always check your browser's JavaScript console for informative error messages provided by GLOW.

Table of Contents​

Before You Start​

  • Confirm you can include an external script in your React or Vue application, typically in your entry point HTML file.
  • Ensure you have a valid retailer ID and product IDs from GLOW.

Setting Up Product Identifiers for GLOW​

GLOW identifies fireworks using two key values:

  • Brand ID: A unique string identifier representing the firework brand.
  • Product ID: A unique string identifier for each firework within that brand.

GLOW provides a list of product IDs based on your catalog, to associate each firework with its 3D simulation. These IDs are typically stored in your database alongside other product information, allowing you to dynamically insert them into your website's product pages.

Load and Initialize the GLOW Library​

Include and initialize the GLOW SDK globally. Typically for a single page application (SPA), you do this once at the root of your React or Vue application. If you're not building an SPA, include this code on every page that uses GLOW.

<!-- Typically in index.html or equivalent entry point -->
<script src="https://glowfireworks.com/sdk/js/v1"></script>
<script>
  glow.initialize({
    retailerId: 'your_retailer_id', // TODO: Replace with your retailer ID
    themeColor: '#0082e6'           // TODO: Adjust to match your brand color
  });
</script>

3D Product Previews​

Handling 3D previews is straightforward – attach a click event and trigger the preview. For SPAs, we ensure preview modals are closed automatically on component unmount.

This preview button can be used anywhere a product is displayed, such as product listings, search results, and detail pages.

GlowPreviewButton.jsx
/**
 * @param {{ brandId: string, productId: string }} props
 */
export const GlowPreviewButton = ({ brandId, productId }) => {
  React.useEffect(() => {
    // Ensure the preview is closed if the component unmounts (e.g., on route change).
    return () => glow.closePreview();
  }, []);

  return (
    <button onClick={() => glow.previewProduct({ brandId, productId })}>
      3D Preview
    </button>
  );
};

API Reference Links:

Add-to-Show Buttons​

Allow users to add fireworks to their custom shows, and automatically synchronize the state across tabs.

The example below uses an optimistic UI update: when the button is clicked, the product is immediately shown as added to the show. If an error occurs (such as a storage permission issue), the state is reverted. GLOW also displays an on-screen error message, so no additional handling is required.

This add-to-show button can be used anywhere a product is displayed, such as product listings, search results, and detail pages, and is typically paired with the preview button above.

Note

To view the current show and remove items, you'll need to embed the Show Builder application. Setup instructions are provided in the next section.

GlowAddToShowButton.jsx
/**
 * @param {{ brandId: string, productId: string }} props
 */
export const GlowAddToShowButton = ({ brandId, productId }) => {
  const [inShow, setInShow] = React.useState(false);

  React.useEffect(() => {
    const unsubscribe = glow.subscribe.isProductInShow({
      brandId,
      productId,
      listener: inShow => setInShow(inShow)
    });
    return unsubscribe;
  }, [brandId, productId]);

  const handleAdd = () => {
    setInShow(true); // optimistic UI update
    glow.addProductToShow({ brandId, productId }).catch(() => {
      setInShow(false); // rollback on failure
    });
  };

  return (
    <button onClick={handleAdd} disabled={inShow}>
      {inShow ? 'In Your Show' : 'Add to Show'}
    </button>
  );
};

API Reference Links:

Embedding the Show Builder Application​

To complete the integration, you'll need to create a dedicated page/route on your website to embed the GLOW Show Builder application. This is the page customers will visit when reviewing and customizing their firework shows.

Step 1: Create the Show Builder Page​

Create the new route, with an appropriate path like /show-builder.

We recommend keeping this page completely empty – no headers, footers, or other elements. The GLOW Show Builder iframe will automatically take over the entire page for the best user experience.

Step 2: Load the Show Builder Application​

Copy the component below into your project, and render it on your new Show Builder route. This component initializes the GLOW Show Builder application on mount, and tears it down when unmounted, like when the user navigates away to a different page.

When users visit this page, they'll see the full-page interactive Show Builder application.

Important

The catalogUrl parameter should point to a full URL (starting with https://) on your website where customers can browse your 3D-enabled fireworks. Ideally this is a product listing page with a filter pre-applied that only shows 3D-supported items. The Show Builder will provide navigation links to the provided URL, helping customers easily return and continue shopping.

GlowShowBuilder.jsx
export const GlowShowBuilder = () => {
  React.useEffect(() => {
    const teardown = glow.createShowBuilder({
      // TODO: Update the `catalogUrl` value with a correct URL.
      catalogUrl: 'https://your-domain.com/products?3d-enabled=1'
    });
    return teardown;
  }, []);

  // No UI here, the Show Builder is created in the effect above.
  return null;
};

API Reference Links:

Providing Convenient Show Builder Access​

The Show Builder is often a central part of a user's shopping experience. To support this, we recommend providing persistent, convenient access to the Show Builder from anywhere on your site.

A common solution is a fixed footer that appears at the bottom of the screen with a prominent "Open Show Builder" button linking to the full Show Builder application setup in the previous step. GLOW supports conditionally displaying this footer only when a user has added at least one product to their show, ensuring it's shown only to engaged users.

You can design this button/link however you like, as long as it remains easy to access. For example, subtly animating the button when a product is added can help draw attention without being disruptive.

Here's a basic example that conditionally shows a persistent footer when the user's show is not empty:

Note

To ensure a footer like this appears above other UI elements, render it at the top level of your application. You may need to adjust the z-index, which is set to 1000 in the following example.

GlowShowLinkFooter.jsx
export const GlowShowLinkFooter = () => {
  const [isVisible, setIsVisible] = React.useState(false);

  React.useEffect(() => {
    const unsubscribe = glow.subscribe.isShowPopulated({
      listener: isShowPopulated => setIsVisible(isShowPopulated)
    });
    return unsubscribe;
  }, []);

  if (!isVisible) {
    return null;
  }

  // TODO: Customize these styles for your site using your preferred styling solution.
  const footerStyle = {
    position: 'fixed',
    zIndex: 1000,
    left: 0,
    right: 0,
    bottom: 0,
    padding: '20px 0',
    backgroundColor: '#fff',
    boxShadow: '0 -6px 12px -3px rgb(0 0 0 / 0.16), 0 -2px 4px -1px rgb(0 0 0 / 0.05)'
  };

  const linkStyle = {
    display: 'block',
    maxWidth: 256,
    margin: '0 auto',
    padding: 12,
    color: '#fff',
    fontSize: 18,
    fontWeight: 'bold',
    textAlign: 'center',
    textDecoration: 'none',
    backgroundColor: '#0077d3',
    borderRadius: 4
  };

  return (
    <div className="glow-show-link-footer" style={footerStyle}>
      {/* TODO: update this link to point to where you're hosting the Show Builder application. */}
      <a href="/show-builder" className="glow-show-link" style={linkStyle}>
        Open Show Builder
      </a>
    </div>
  );
};

API Reference Links:

Official Show Previews​

If you sell pre-built shows, you can embed inline 3D show previews just like your product previews. To enable this, you'll need the show ID, which is found in your published show links. For example, if your show link is glfw.io/share/2ZH232T, the show ID is 2ZH232T.

GlowShowPreviewButton.jsx
/**
 * @param {{ showId: string }} props
 */
export const GlowShowPreviewButton = ({ showId }) => {
  React.useEffect(() => {
    // Ensure the preview is closed if the component unmounts (e.g., on route change).
    return () => glow.closePreview();
  }, []);

  return (
    <button onClick={() => glow.previewShow({ showId })}>
      3D Show Preview
    </button>
  );
};

API Reference Links:

Bringing It All Together​

Add the components above to your project and verify they work as expected. Below is a minimal example you can use to test all components.

  • The GLOW library is loaded in an entry HTML file.
  • A test page renders all buttons with sample firework IDs.
  • A dedicated Show Builder page is created.
  • You will need to incorporate the new pages into your routing system.

The test page is intended as a temporary, throwaway tool for verifying functionality. Do not include it in production. Once you've confirmed everything works, you can integrate the buttons into real product pages and apply your final styling.

index.html
<div id="app"></div>

<script src="https://glowfireworks.com/sdk/js/v1"></script>
<script>
  glow.initialize({
    retailerId: 'your_retailer_id', // TODO: Replace with your retailer ID
    themeColor: '#0082e6'           // TODO: Adjust to match your brand color
  });
</script>
TestPage.jsx
// TODO: update import paths if needed.
import { GlowPreviewButton } from './GlowPreviewButton';
import { GlowAddToShowButton } from './GlowAddToShowButton';
import { GlowShowPreviewButton } from './GlowShowPreviewButton';
import { GlowShowLinkFooter } from './GlowShowLinkFooter';

export const TestPage = () => {
  const rowStyle = {
    display: 'flex',
    justifyContent: 'center',
    gap: '1em'
  };

  return (
    <>
      <div style={rowStyle}>
        {/* These hardcoded IDs work, but in practice you'll use dynamic IDs from your database. */}
        <GlowPreviewButton brandId="sample" productId="demo-500g" />
        <GlowAddToShowButton brandId="sample" productId="demo-500g" />
        <GlowShowPreviewButton showId="DDTZ8RF" />
      </div>
      {/* Footer placed at top level of page */}
      <GlowShowLinkFooter />
    </>
  );
};
ShowBuilderPage.jsx
import { GlowShowBuilder } from './GlowShowBuilder';

// The Show Builder page can be as simple as just rendering this component.
export const ShowBuilderPage = () => <GlowShowBuilder />;

Final Checklist​

  • Include the GLOW <script> tag and call glow.initialize() with your retailer ID.
  • Test all 3D preview and add-to-show buttons, confirming they work as expected.
  • After adding fireworks, ensure a link appears that navigates to the Show Builder application.
  • Confirm Show Builder correctly displays the added products.
  • In the Show Builder application, clicking your logo takes you to an appropriate page on your site to browse 3D products.
  • Check browser console for GLOW-related errors on any pages using our library.

Promoting the 3D Show Builder​

To maximize engagement, it's essential to make the 3D Show Builder easy to discover. We recommend the following promotional strategies:

  • Add a main navigation link: Include a direct link to the 3D Show Builder in your website's main navigation. This should point to an appropriate page on your site where customers can browse 3D products.
  • Homepage callout: Feature a high-visibility banner or other callout on your homepage to introduce customers to the 3D Show Builder.
  • Leverage marketing channels: Promote the experience across social media, email campaigns, and print materials to drive traffic and awareness.

Troubleshooting & Common Errors​

  • Error Messages: GLOW provides clear, actionable error messages in the browser console – always check there first.

  • Loading the GLOW library more than once? Ensure the library is loaded only once per page/session. If our script tag is included on a page multiple times (which can sometimes happen accidentally with automated script loading setups), an error will be logged to the console and some functionality may not work as expected.

  • Buttons Not Working? Confirm our script is loaded once and glow.initialize() is called before invoking additional functionality. If you confirmed this is set up properly and you don't see any initialization errors in the console, you'll have to debug your component code further. If you suspect something isn't working as it should, feel free to reach out.