1.3.171 • Published 8 months ago

@zonos/elements v1.3.171

Weekly downloads
-
License
MIT
Repository
github
Last release
8 months ago

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 contents

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:

    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

      import "@zonos/elements";

    • Create a ContextProvider

        '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

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

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

      import { useContext } from 'react';

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

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

    • Create component called ZonosLayoutSetup.tsx to initialize Zonos.

      '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

      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.

      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 ManagerCommand
pnpmpnpm add @zonos/elements
npmnpm install @zonos/elements
yarnyarn add @zonos/elements

React, Next.js:

  • Create a component called ZonosLayoutSetup.tsx

    '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

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

API references

Zonos instance definition

Single file definition for Zonos instance

Zonos.init - checkoutSettings available configurations

Zonos.init - helloSettings available configurations

@paypal/paypal-js@stencil/corefuse.jsgraphql-requestlodashtinycolor2turndown
@everything-registry/sub-chunk-1079
1.3.171

8 months ago

1.3.170

8 months ago

1.3.168

8 months ago

1.3.169

8 months ago

1.3.167

8 months ago

1.3.166

8 months ago

1.3.165

8 months ago

1.3.164

8 months ago

1.3.163

8 months ago

1.3.162

8 months ago

1.3.157

9 months ago

1.3.156

9 months ago

1.3.155

9 months ago

1.3.154

9 months ago

1.3.159

9 months ago

1.3.158

9 months ago

1.3.152

9 months ago

1.3.151

9 months ago

1.3.160

9 months ago

1.3.161

9 months ago

1.3.149

10 months ago

1.3.148

10 months ago

1.3.150

9 months ago

1.3.146

10 months ago

1.3.147

10 months ago

1.3.145

10 months ago

1.3.144

10 months ago

1.3.143

10 months ago

1.3.142

11 months ago

1.3.141

11 months ago

1.3.140

11 months ago

1.3.139

11 months ago

1.3.138

11 months ago

1.3.137

11 months ago

1.3.136

11 months ago

1.3.135

11 months ago

1.3.134

11 months ago

1.3.133

11 months ago

1.3.132

11 months ago

1.3.131

11 months ago

1.3.130

11 months ago

1.3.129

12 months ago

1.3.128

12 months ago

1.3.117

12 months ago

1.3.116

12 months ago

1.3.115

12 months ago

1.3.119

12 months ago

1.3.118

12 months ago

1.3.124

12 months ago

1.3.123

12 months ago

1.3.122

12 months ago

1.3.121

12 months ago

1.3.127

12 months ago

1.3.126

12 months ago

1.3.125

12 months ago

1.3.120

12 months ago

1.3.113

12 months ago

1.3.112

12 months ago

1.3.111

12 months ago

1.3.110

1 year ago

1.3.114

12 months ago

1.3.109

1 year ago

1.3.106

1 year ago

1.3.108

1 year ago

1.3.107

1 year ago

1.3.105

1 year ago

1.3.104

1 year ago

1.3.102

1 year ago

1.3.101

1 year ago

1.3.100

1 year ago

1.3.103

1 year ago

1.3.98

1 year ago

1.3.99

1 year ago

1.3.97

1 year ago

1.3.96

1 year ago

1.3.93

1 year ago

1.3.94

1 year ago

1.3.95

1 year ago

1.3.90

1 year ago

1.3.91

1 year ago

1.3.92

1 year ago

1.3.87

1 year ago

1.3.88

1 year ago

1.3.89

1 year ago

1.3.57

1 year ago

1.3.58

1 year ago

1.3.59

1 year ago

1.3.60

1 year ago

1.3.61

1 year ago

1.3.64

1 year ago

1.3.65

1 year ago

1.3.62

1 year ago

1.3.63

1 year ago

1.3.68

1 year ago

1.3.69

1 year ago

1.3.66

1 year ago

1.3.67

1 year ago

1.3.71

1 year ago

1.3.72

1 year ago

1.3.70

1 year ago

1.3.75

1 year ago

1.3.76

1 year ago

1.3.73

1 year ago

1.3.74

1 year ago

1.3.79

1 year ago

1.3.77

1 year ago

1.3.78

1 year ago

1.3.82

1 year ago

1.3.83

1 year ago

1.3.80

1 year ago

1.3.81

1 year ago

1.3.86

1 year ago

1.3.84

1 year ago

1.3.85

1 year ago

1.3.50

1 year ago

1.3.53

1 year ago

1.3.54

1 year ago

1.3.51

1 year ago

1.3.52

1 year ago

1.3.55

1 year ago

1.3.56

1 year ago

1.3.39

1 year ago

1.3.38

1 year ago

1.3.42

1 year ago

1.3.43

1 year ago

1.3.40

1 year ago

1.3.41

1 year ago

1.3.46

1 year ago

1.3.47

1 year ago

1.3.44

1 year ago

1.3.45

1 year ago

1.3.48

1 year ago

1.3.49

1 year ago

1.3.37

1 year ago

1.3.35

1 year ago

1.3.36

1 year ago

1.3.34

1 year ago

1.3.32

1 year ago

1.3.33

1 year ago

1.3.34-alpha.0

1 year ago

1.3.31

1 year ago

1.3.30

1 year ago

1.3.29

1 year ago

1.3.28

1 year ago

1.3.19

1 year ago

1.3.20-alpha.0

1 year ago

1.3.20-alpha.1

1 year ago

1.3.20

1 year ago

1.3.21

1 year ago

1.3.24

1 year ago

1.3.25

1 year ago

1.3.22

1 year ago

1.3.23

1 year ago

1.3.26

1 year ago

1.3.27

1 year ago

1.3.25-alpha.0

1 year ago

1.3.18

1 year ago

1.3.18-alpha.4

1 year ago

1.3.18-alpha.3

1 year ago

1.3.18-alpha.2

1 year ago

1.3.18-alpha.1

1 year ago

1.3.17

1 year ago

1.3.18-alpha.0

1 year ago

1.3.16

1 year ago

1.3.16-alpha.0

1 year ago

1.3.15

1 year ago

1.3.15-alpha.3

1 year ago

1.3.15-alpha.2

1 year ago

1.3.15-alpha.1

1 year ago

1.3.14

1 year ago

1.3.15-alpha.0

1 year ago

1.3.14-alpha.0

2 years ago

1.3.13

2 years ago

1.3.13-alpha.2

2 years ago

1.3.13-alpha.1

2 years ago

1.3.12

2 years ago

1.3.13-alpha.0

2 years ago

1.3.12-alpha.10

2 years ago

1.3.12-alpha.11

2 years ago

1.3.12-alpha.12

2 years ago

1.3.12-alpha.9

2 years ago

1.3.12-alpha.8

2 years ago

1.3.12-alpha.7

2 years ago

1.3.12-alpha.6

2 years ago

1.3.12-alpha.3

2 years ago

1.3.12-alpha.5

2 years ago

1.3.12-alpha.4

2 years ago

1.3.12-alpha.2

2 years ago

1.3.12-alpha.1

2 years ago

1.3.12-alpha.0

2 years ago

1.3.11

2 years ago

1.3.11-alpha.2

2 years ago

1.3.11-alpha.3

2 years ago

1.3.11-alpha.1

2 years ago

1.3.11-alpha.0

2 years ago

1.3.10

2 years ago

1.3.10-alpha.1

2 years ago

1.3.10-alpha.0

2 years ago

1.3.10-alpha.2

2 years ago

1.3.8-alpha.5

2 years ago

1.3.8-alpha.3

2 years ago

1.3.8-alpha.4

2 years ago

1.3.9

2 years ago

1.3.8

2 years ago

1.3.8-alpha.2

2 years ago

1.3.8-alpha.1

2 years ago

1.3.7

2 years ago

1.3.8-alpha.0

2 years ago

1.3.7-alpha.1

2 years ago

1.3.7-alpha.0

2 years ago

1.3.6

2 years ago

1.3.5

2 years ago

1.3.5-alpha.0

2 years ago

1.3.4

2 years ago

1.3.4-alpha.2

2 years ago

1.3.4-alpha.1

2 years ago

1.3.4-alpha.0

2 years ago

1.3.3

2 years ago

1.3.2

2 years ago

1.3.3-alpha.0

2 years ago

1.2.4-alpha.14

2 years ago

1.2.4-alpha.13

2 years ago

1.2.4-alpha.12

2 years ago

1.2.4-alpha.10

2 years ago

1.2.4-alpha.11

2 years ago

1.2.4-alpha.8

2 years ago

1.2.4-alpha.7

2 years ago

1.2.4-alpha.6

2 years ago

1.2.4-alpha.5

2 years ago

1.2.4-alpha.4

2 years ago

1.2.4-alpha.3

2 years ago

1.2.4-alpha.1

2 years ago

1.2.4-alpha.2

2 years ago

1.2.3

2 years ago

1.2.2

2 years ago

1.2.1

2 years ago

1.2.0

2 years ago

1.1.2

2 years ago

1.0.17-alpha.1

2 years ago

1.0.17-alpha.0

2 years ago

1.1.1

2 years ago

1.0.16

2 years ago