Zonos Component UI Introduction

This project offers web components designed primarily for Zonos Checkout, Zonos Hello, and other Zonos products, with a focus on React and Next.js integration. Although not yet tested with other JavaScript libraries and frameworks, the implementation principles for React and Next.js can be adapted for use with other frameworks. For more information about Zonos products, please visit the official Zonos website.

Table of content

Zonos Component UI Introduction
Table of content
Prerequisites
Installation
API references

Prerequisites

Node.js (v18 or higher)
An API key for Zonos Checkout/Hello (please contact our support team for more information)

Installation

There are two ways to initialize Zonos: via custom integration using a CDN or through npm installation.

Note: All methods below are only using the base configuration to have the Checkout and Hello up and running. For a more secure way to build your cart, please check out our docs for more information.

Brief `Zonos.init` base configuration explanation:

checkoutSettings.buildCartDetail: This callback function retrieves cart item information from your web platform. It should return an array of cart item objects. For the expected type definition, please refer to the buildCartDetail and the cart item files.
checkoutSettings.placeOrderButtonSelector: This is used to find all matching selectors and attach an event to trigger the Checkout process. While you can configure this in our Zonos dashboard, it's recommended to set it here so that Zonos can disable your Checkout place order button while loading.
zonosApiKey: An API key for Zonos Checkout/Hello (please contact our support team for more information).
storeId: Store id that your checkout would associate with (please contact our support team for more information).

CDN

CDN when to use:

This is suitable for you if you:

Use any non-JavaScript frameworks (e.g., PHP, Java, C#).
Have a static site with pure HTML, CSS, and JavaScript.
Do not need type references in the project.
Prefer to use a CDN even if you are using a JavaScript framework (e.g., React, Vue, Next.js).
Want to quickly test how Zonos functions on your site (e.g., easily drop the script snippet into the Console tab in your browser's developer tools).

CDN usage:

For non-JavaScript frameworks:

Copy and paste the following into your HTML or the "Console" tab of your browser's developer tool

Put the <script> tag below into the <head> tag of your HTML:

<script>
  (async function () {
    const zonosElementsUrl = 'https://js.zonos.com';
    const timestamp = new Date().getTime();
    const zonosScript = document.querySelector(
      `script[src*="${zonosElementsUrl}/dist/scripts/loadZonos.js"]`,
    );

    if (!zonosScript) {
      const script = document.createElement('script');
      script.src = `${zonosElementsUrl}/dist/scripts/loadZonos.js?timestamp=${timestamp}`;
      script.addEventListener(
        'load',
        () => {
          const getCartItems = async () => {
            const yourServerUrl = "https://your-server.com/api/get-cart-items";
            const response = await fetch(yourServerUrl);
            const json = await response.json();
            return json;
          };

          // Initialize Zonos with your store's settings.
          // Replace '<%= placeOrderButtonSelector %>', '<%= storeId %>', and '<%= credentialToken %>'
          // with your actual values.
          void window.Zonos.init({
            checkoutSettings: {
              buildCartDetail: async () => {
                const allItems = getCartItems();
                return allItems;
              },
              placeOrderButtonSelector: '<%= placeOrderButtonSelector %>',
            },
            storeId: Number('<%= storeId %>'), // Contact support for this information.
            zonosApiKey: '<%= credentialToken %>', // Contact support for this information
          });
        },
        false,
      );
      document.head.appendChild(script);
    }
  })();
</script>

For React, Next.js:

Create a typescript file and import @zonos/elements to define types definition for window interface
Code example
```
import "@zonos/elements";
```

Create a ContextProvider

Code example

  'use client';
  import { type ReactNode, createContext, useMemo, useState } from 'react';

  import Script from 'next/script';

  type ZonosScriptProps = {
    scriptLoaded: boolean;
  };

  export const ZonosScriptContext = createContext<ZonosScriptProps>({
    scriptLoaded: false,
  });

  export const ZonosScriptContextProvider = ({
    children,
  }: {
    children: ReactNode;
  }) => {
    const [scriptLoaded, setScriptLoaded] = useState(false);

    const context: ZonosScriptProps = {
      scriptLoaded,
    };
    const timestamp = useMemo(() => Date.now(), []);
    return (
      <ZonosScriptContext.Provider value={context}>
        <Script
          onLoad={() => setScriptLoaded(true)}
          src={`https://js.zonos.com/dist/scripts/loadZonos.js?timestamp=${timestamp}`}
        />
        {children}
      </ZonosScriptContext.Provider>
    );
  };

Wrap ZonosScriptContextProvider into root of your layout.tsx

Code example

export default function Layout({ children }:{ children: ReactNode}) {
  return (
    <ZonosScriptContextProvider>
      <main>
        {children}
      </main>
    </ZonosScriptContextProvider>
  )
}

Create a hook named useZonosScript.ts to use the context easier

Code example

import { useContext } from 'react';

import { ZonosScriptContext } from 'src/components/ZonosScriptContext';

export const useZonosScript = () => useContext(ZonosScriptContext);

Create component called ZonosLayoutSetup.tsx to initialize Zonos.

Code example

'use client';
import { type ReactNode, useEffect } from 'react';

import { useZonosScript } from 'src/utils/hooks/useZonosScript';

export const ZonosLayoutSetup = ({ children }: { children: ReactNode }) => {
  const { scriptLoaded } = useZonosScript();

  useEffect(() => {
    // Only initialize Zonos when zonos script is fully loaded.
    if (!scriptLoaded) {
      return;
    }
    const getCartItems = async () => {
      const yourServerUrl = "https://your-server.com/api/get-cart-items";
      const response = await fetch(yourServerUrl);
      const json = await response.json();
      return json;
    };

    // Initialize Zonos with your store's settings.
    // Replace '<%= placeOrderButtonSelector %>', '<%= storeId %>', and '<%= credentialToken %>'
    // with your actual values.
    void window.Zonos.init({
      checkoutSettings: {
        buildCartDetail: async () => {
          const allItems = getCartItems();
          return allItems;
        },
        placeOrderButtonSelector: '<%= placeOrderButtonSelector %>',
      },
      storeId: Number('<%= storeId %>'), // Contact support for this information.
      zonosApiKey: '<%= credentialToken %>', // Contact support for this information
    });
  }, [scriptLoaded]);

  return children;
};

Put component ZonosLayoutSetup.tsx right under ZonosScriptContextProvider

Code example

export default function Layout({ children }:{ children: ReactNode}) {
  return (
    <ZonosScriptContextProvider>
      <ZonosLayoutSetup>
        <main>
          {children}
        </main>
      </ZonosLayoutSetup>
    </ZonosScriptContextProvider>
  )
}

For javascript framework that's not React, Next.js:
- Create a typescript file and import @zonos/elements to define types definition for window interface. You will have access to window.Zonos through out of your project if you are using typescript.
  Code example
```
import "@zonos/elements";
```

Npm

Npm when to use:

This method is ideal if you are using TypeScript with modern JavaScript frameworks, particularly React and Next.js. It provides strong typing for the window.Zonos.init function, making setup easier and enabling auto-completion in TypeScript-enabled environments.

Npm usage:

Install @zonos/elements:

Package Manager	Command
pnpm	`pnpm add @zonos/elements`
npm	`npm install @zonos/elements`
yarn	`yarn add @zonos/elements`

React, Next.js:

Create a component called ZonosLayoutSetup.tsx

Code example

'use client';
import { type ReactNode, useEffect } from 'react';

import { Zonos } from '@zonos/elements';

import { useZonosScript } from 'src/utils/hooks/useZonosScript';

export const ZonosLayoutSetup = ({ children }: { children: ReactNode }) => {
  useEffect(() => {
    // Initialize Zonos into `window` API.
    window.Zonos = Zonos;

    const getCartItems = async () => {
      const yourServerUrl = "https://your-server.com/api/get-cart-items";
      const response = await fetch(yourServerUrl);
      const json = await response.json();
      return json;
    };
    

    // Initialize Zonos
    void window.Zonos.init({
      checkoutSettings: {
        buildCartDetail: async () => {
          const allItems = getCartItems();
          return allItems;
        },
        placeOrderButtonSelector: '<%= placeOrderButtonSelector %>',
      },
      storeId: Number('<%= storeId %>'), // Contact support for this information.
      zonosApiKey: '<%= credentialToken %>', // Contact support for this information
    });
  }, [scriptLoaded]);

  return children;
};

Put component ZonosLayoutSetup.tsx at top level of your layout.tsx

Code example

export default function Layout({ children }:{ children: ReactNode}) {
  return (
    <ZonosLayoutSetup>
      <main>
        {children}
      </main>
    </ZonosLayoutSetup>
  )
}

Name		Name	Last commit message	Last commit date
Latest commit History 55 Commits
.husky		.husky
__tests__		__tests__
dist		dist
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
vitest.config.mts		vitest.config.mts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Zonos Component UI Introduction

Table of content

Prerequisites

Installation

Brief `Zonos.init` base configuration explanation:

CDN

CDN when to use:

CDN usage:

Npm

Npm when to use:

Npm usage:

API references

Zonos instance definition

Single file definition for Zonos instance

Zonos.init - checkoutSettings available configurations

Zonos.init - helloSettings available configurations

About

Releases

Packages

Contributors 2

Languages

License

Zonos/zonos-elements-readme

Folders and files

Latest commit

History

Repository files navigation

Zonos Component UI Introduction

Table of content

Prerequisites

Installation

Brief Zonos.init base configuration explanation:

CDN

CDN when to use:

CDN usage:

Npm

Npm when to use:

Npm usage:

API references

Zonos instance definition

Single file definition for Zonos instance

Zonos.init - checkoutSettings available configurations

Zonos.init - helloSettings available configurations

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Languages

Brief `Zonos.init` base configuration explanation:

Packages