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

# Vue

> Integrate Commerce Engine Checkout into Vue 3 apps with the useCheckout composable. Returns reactive refs with automatic cleanup.

### NPM Package

<Card title="@commercengine/checkout" icon="npm" href="https://www.npmjs.com/package/@commercengine/checkout">
  Vue integration for Commerce Engine Checkout.
</Card>

### Installation

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npm install @commercengine/checkout
```

### Setup

Call `initCheckout` once at your app's entry point. The SDK resolves the hosted URL from `storeId` + `environment` using store-specific subdomains:

```ts main.ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { createApp } from "vue";
import { initCheckout } from "@commercengine/checkout/vue";
import App from "./App.vue";

initCheckout({
  storeId: "store_xxx",
  apiKey: "ak_xxx",
  environment: "production",
});

createApp(App).mount("#app");
```

### Use the composable

`useCheckout()` returns reactive refs and action methods. Call it inside `setup()` or `<script setup>`.

```vue CartButton.vue theme={"theme":{"light":"github-light","dark":"github-dark"}}
<script setup lang="ts">
import { useCheckout } from "@commercengine/checkout/vue";

const { openCart, cartCount, isReady } = useCheckout();
</script>

<template>
  <button @click="openCart" :disabled="!isReady">
    Cart ({{ cartCount }})
  </button>
</template>
```

### Full example

```vue App.vue theme={"theme":{"light":"github-light","dark":"github-dark"}}
<script setup lang="ts">
import { useCheckout } from "@commercengine/checkout/vue";

const {
  openCart,
  openCheckout,
  cartCount,
  isReady,
  isLoggedIn,
  user,
  addToCart,
} = useCheckout();
</script>

<template>
  <nav>
    <span v-if="isLoggedIn">Hi, {{ user?.firstName }}</span>
    <button @click="openCart" :disabled="!isReady">
      Cart ({{ cartCount }})
    </button>
  </nav>

  <main>
    <button @click="addToCart('product_abc', 'variant_xyz')">
      Add to Cart
    </button>
  </main>
</template>
```

### Nuxt

For Nuxt 3, create a plugin to initialize checkout:

```ts plugins/checkout.client.ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { initCheckout } from "@commercengine/checkout/vue";

export default defineNuxtPlugin(() => {
  initCheckout({
    storeId: "store_xxx",
    apiKey: "ak_xxx",
    environment: "production",
  });
});
```

The `.client.ts` suffix ensures this only runs in the browser. Then use `useCheckout()` in any component.

<Info>
  Feature flags, login methods, drawer direction, and payment provider are managed in Checkout Studio (Config API), not as SDK init options. Use `theme` only for per-session overrides.
</Info>

### Syncing external auth

```vue AuthSync.vue theme={"theme":{"light":"github-light","dark":"github-dark"}}
<script setup lang="ts">
import { watch } from "vue";
import { useCheckout } from "@commercengine/checkout/vue";

const props = defineProps<{
  accessToken: string;
  refreshToken?: string;
}>();

const { updateTokens } = useCheckout();

watch(
  () => props.accessToken,
  (token) => {
    if (token) updateTokens(token, props.refreshToken);
  },
  { immediate: true }
);
</script>
```

### Composable API reference

`useCheckout()` returns:

| Property                                     | Type                              | Description                               |
| -------------------------------------------- | --------------------------------- | ----------------------------------------- |
| `isReady`                                    | `Readonly<Ref<boolean>>`          | `true` when the checkout iframe is loaded |
| `isOpen`                                     | `Readonly<Ref<boolean>>`          | `true` when the overlay is visible        |
| `cartCount`                                  | `Readonly<Ref<number>>`           | Number of items in the cart               |
| `cartTotal`                                  | `Readonly<Ref<number>>`           | Cart subtotal                             |
| `cartCurrency`                               | `Readonly<Ref<string>>`           | Currency code                             |
| `isLoggedIn`                                 | `Readonly<Ref<boolean>>`          | Whether a user is logged in               |
| `user`                                       | `Readonly<Ref<UserInfo \| null>>` | Current user info                         |
| `openCart()`                                 | `function`                        | Open the cart drawer                      |
| `openCheckout()`                             | `function`                        | Open checkout directly                    |
| `close()`                                    | `function`                        | Close the overlay                         |
| `addToCart(productId, variantId, quantity?)` | `function`                        | Add an item to the cart                   |
| `updateTokens(accessToken, refreshToken?)`   | `function`                        | Sync auth tokens                          |

All state properties are readonly Vue refs. They update automatically when the checkout state changes and clean up on component unmount.