> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoply.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# npm and React

> The SDK, the embed and the Checkout Kit as packages, with types, and as React components

The SDK, the [embed](/guides/embeds.md) and the [Checkout Kit](/guides/checkout-kit.md) are each one script tag. On a site built with npm, two packages put them in your code instead:

| | |
| - | - |
| **`@shoplygg/js`** | The three, loaded when a page first needs them, with TypeScript types |
| **`@shoplygg/react`** | The same as React components and hooks, for React 18 or newer |

```sh theme={null}
npm install @shoplygg/js
# or, with React
npm install @shoplygg/react
```

Both load Shoply's own hosted scripts from shoply.gg, the same files a script tag loads. A fix to one reaches your site without you updating the package. Each script is loaded once a page, the first time something asks for it.

They run in the browser. With a framework that renders on a server (Next.js, Remix), the React components draw their element there and start once they are in the browser. With `@shoplygg/js`, call it from an effect or an event handler, not while rendering.

## With React

### The SDK

```jsx theme={null}
import { ShoplyProvider, useShoply, usePageView } from "@shoplygg/react";

export default function Layout({ children }) {
  return <ShoplyProvider storeId="YOUR_STORE_ID">{children}</ShoplyProvider>;
}

function Products() {
  const { shoply, ready } = useShoply();
  // shoply.getProducts(), shoply.addToBasket(), shoply.checkout(email)...
}
```

`shoply` is null until the SDK has started. Every method is in the [SDK reference](/sdk/reference.md). `options` on the provider are `shoply.init()`'s, such as `currency` and `track`.

A site whose router changes the page without loading one counts each page it shows:

```jsx theme={null}
usePageView(pathname);
```

### The embed

```jsx theme={null}
import { EmbedButton } from "@shoplygg/react";

<EmbedButton product="PRODUCT_ID" variant="VARIANT_ID" className="buy" onPaid={() => router.push("/thanks")}>
  Buy now
</EmbedButton>
```

A button that opens the checkout over the page. It takes the embed's options (`product`, `variant`, `quantity`, `coupon`, `theme`, `email`, `billing`) and anything a button takes. `useEmbed()` answers `open` and `close`, to open it from anywhere else.

### The Checkout Kit

```jsx theme={null}
import { CheckoutKit, KitPiece, useCheckoutKit } from "@shoplygg/react";

<CheckoutKit items={basket} look={{ accent: "#12a37f", radius: 6 }} onPaid={() => router.push("/thanks")}>
  <aside>
    <KitPiece name="summary" />
  </aside>
  <main>
    <KitPiece name="email" />
    <KitPiece name="payment" />
    <KitPiece name="pay" />
  </main>
</CheckoutKit>
```

Put the pieces anywhere under `<CheckoutKit>`, one of them `checkout` or `payment`. Its options are the Kit's, and a change to them after it is up (the cart, the look) is passed to the Kit, so the checkout follows your page's own basket. `useCheckoutKit()` answers the Kit, for `kit.pay()` from a button of your own.

`onPaid` tells the page only: it is no proof of payment. Your server hears of a paid order from [webhooks](/guides/webhooks.md).

## Without React

```js theme={null}
import { initShoply, openEmbed, onCheckout, createKit } from "@shoplygg/js";

const shoply = await initShoply("YOUR_STORE_ID");
const store = await shoply.getStore();

button.addEventListener("click", () => openEmbed({ product: "PRODUCT_ID" }));
onCheckout({ onPaid: () => showThanks() });

const kit = await createKit({ product: "PRODUCT_ID" });
kit.place("payment", "#payment").place("summary", "#order");
```

| | |
| - | - |
| **`initShoply(storeId, options)`** | Loads the SDK and starts it for your store, once a page |
| **`loadShoply()`** | Loads the SDK without starting it |
| **`openEmbed(options)`** | Opens the checkout over the page |
| **`loadEmbed()`** | Loads the embed: `{ open, close }` |
| **`onCheckout({ onPaid, onClose })`** | Listens for an order paid through the embed or the Kit. Answers a function that stops listening. |
| **`createKit(options)`** | Makes a Checkout Kit, with every element marked `data-shoply-piece` placed |
| **`loadKit()`** | Loads the Kit: the `shoplyKit()` function |

## Types

Both packages carry TypeScript types: the store, products, variants, the basket, the embed's and the Kit's options and events. A field Shoply adds later is there before the types name it, as `unknown`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.