# Events


Handle user actions and order lifecycle through the `<gett-marketfront>` element's events.

:::tip
Event names, signatures, and payload shapes are listed in the [SDK Reference](/distribution-partners/marketfront-sdk/sdk-reference/events). Payload types (`MarketfrontError`, `Order`, etc.) ship as `.d.ts` in the npm package — your IDE will surface them inline. This guide focuses on practical usage patterns.
:::

## Handling Events

Every `<gett-marketfront>` event is a [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) — subscribe with `addEventListener` and read the payload from `event.detail`.

```typescript
import '@gett-co/marketfront';

const el = document.querySelector('gett-marketfront')!;

el.addEventListener('ready', () => console.log('Ready'));
el.addEventListener('order-complete', (e) => {
  console.log('Order placed:', e.detail.id);
});
```

### React 19

React 19 binds custom-element `on*` props case-preservingly, so the JSX prop name mirrors the dispatched kebab-case event name. The callback receives the `CustomEvent` itself.

```tsx
<gett-marketfront onorder-complete={(e) => console.log(e.detail.id)} />
```

## Event Reference

### Lifecycle Events

#### `ready`

Fired when the marketfront has fully initialized and is ready for interaction.

```typescript
el.addEventListener('ready', () => {
  console.log('Marketfront ready');
  hideLoadingSpinner();
});
```

#### `error`

Fired when an error occurs. Payload is a `MarketfrontError` (`code`, `message`, optional `details`).

```typescript
el.addEventListener('error', (e) => {
  console.error(`[${e.detail.code}] ${e.detail.message}`);
  showErrorNotification(e.detail.message);
});
```

### Store Events

#### `store-selected`

Fired when the user selects a store to order from.

```typescript
el.addEventListener('store-selected', (e) => {
  console.log('Store selected', e.detail);
});
```

### Cart Events

#### `item-added`

Fired when an item is added to the cart.

```typescript
el.addEventListener('item-added', (e) => {
  console.log('Item added to cart', e.detail);
});
```

### Checkout Events

#### `checkout-started`

Fired when the user begins the checkout process.

```typescript
el.addEventListener('checkout-started', (e) => {
  console.log('Checkout started', e.detail);
});
```

### Order Events

#### `order-complete`

Fired when the order is successfully placed. This is the most important event for most integrations. Payload is an `Order` carrying at minimum the placed order's `id`.

```typescript
el.addEventListener('order-complete', (e) => {
  console.log('Order placed:', e.detail.id);

  // Navigate to confirmation
  router.push(`/order/${e.detail.id}`);
});
```

## Analytics Integration

Use event listeners to track user behavior:

```typescript
import '@gett-co/marketfront';

const el = document.querySelector('gett-marketfront')!;

el.addEventListener('item-added', () => {
  gtag('event', 'add_to_cart', { currency: 'USD' });
});

el.addEventListener('checkout-started', () => {
  gtag('event', 'begin_checkout', { currency: 'USD' });
});

el.addEventListener('order-complete', (e) => {
  gtag('event', 'purchase', {
    transaction_id: e.detail.id,
    currency: 'USD',
  });
});
```

## Framework Examples

### React 19

```tsx
import '@gett-co/marketfront';

function OrderPage({ sessionToken }: { sessionToken: string }) {
  return (
    <gett-marketfront
      session-token={sessionToken}
      onready={() => console.log('Ready')}
      onorder-complete={(e) => {
        trackPurchase(e.detail);
        router.push(`/order/${e.detail.id}`);
      }}
      onerror={(e) => showToast(e.detail.message)}
    />
  );
}
```

### Vue

```vue
<script setup lang="ts">
import '@gett-co/marketfront';
import { useRouter } from 'vue-router';

const router = useRouter();
</script>

<template>
  <gett-marketfront
    :session-token="sessionToken"
    @order-complete="(e: CustomEvent) => router.push(`/order/${e.detail.id}`)"
    @error="(e: CustomEvent) => console.error(e.detail)"
  />
</template>
```

### Angular

```typescript
import { Component, CUSTOM_ELEMENTS_SCHEMA, Input } from '@angular/core';
import { Router } from '@angular/router';
import '@gett-co/marketfront';

@Component({
  selector: 'app-order',
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <gett-marketfront
      [attr.session-token]="sessionToken"
      (order-complete)="onOrder($event)"
      (error)="onError($event)"
    ></gett-marketfront>
  `,
})
export class OrderComponent {
  @Input() sessionToken!: string;

  constructor(private router: Router) {}

  onOrder(event: CustomEvent) {
    this.router.navigate(['/order', event.detail.id]);
  }

  onError(event: CustomEvent) {
    console.error('Marketfront error:', event.detail);
  }
}
```

## Next Steps

- **[Sessions](/distribution-partners/marketfront-sdk/guides/sessions)** -- Session creation and consumer context
- **[PCI Compliance](/distribution-partners/shared-guides/payments#pci-compliance)** -- Payment security