# salla-loyalty (https://docs.salla.dev/twilight/react/web-components/salla-loyalty)



{/* Generated by scripts/sync-web-components.mjs from the components docs.json. Do not edit by hand. */}

The loyalty program (points) feature for the cart: a "you have N points, exchange now" banner, a popup listing the
prizes the customer can exchange points for, and a confirmation step. Use it once on the cart page (it is also safe in the layout).
Pass `customer-points` to show the default banner; once a prize has been exchanged (`prize-points` is set, which the
component also updates itself from cart updates) it shows the exchanged prize with a reset button instead.
The popup opens when the `loyalty::open` event fires or `open()` is called; guests are sent to the login popup (`login::open`) instead.

## Use it [#use-it]

In HTML or JSX, use the tag `<salla-loyalty>` with the **Attribute** names below. In React, the wrapper takes the **Property** names (camelCase).

```tsx
import { SallaLoyalty } from '@salla.sa/twilight-components-react/loyalty';
```

**Client-only.** On the server this wrapper renders a placeholder (a skeleton, or nothing), and the real component mounts in the browser. Do not rely on it for content that search engines must see.

## Example [#example]

```tsx
import { useEffect } from 'react';
import { SallaLoyalty } from '@salla.sa/twilight-components-react/loyalty';

export function Example() {
  useEffect(() => {
    document.querySelector('salla-loyalty').open();
  }, []);

  return (
    <SallaLoyalty customerPoints={250} />
  );
}
```

```html
<salla-loyalty customer-points="250"></salla-loyalty>
<script>
  document.querySelector('salla-loyalty').open();
</script>
```

## Properties [#properties]

| Property         | Attribute         | Description                                                                                                                                                                                                                 | Type               | Default |
| ---------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------- |
| `allowEmail`     | `allow-email`     | Does the merchant allow to login using email **Deprecated:** Not read by the component, so it has no effect. It will be removed in the next major version.                                                                  | `boolean`          | `true`  |
| `allowMobile`    | `allow-mobile`    | Does the merchant/current location for visitor allow to login using mobile, By default outside KSA is `false` **Deprecated:** Not read by the component, so it has no effect. It will be removed in the next major version. | `boolean`          | `true`  |
| `customerPoints` | `customer-points` | The customer's available points balance (a count of points). The default banner is only shown when this is non-zero. Updated automatically from cart updates.                                                               | `number`           |         |
| `guestMessage`   | `guest-message`   | Message to show for guest users.                                                                                                                                                                                            | `string`           |         |
| `prizePoints`    | `prize-points`    | Points already spent on the exchanged prize in the current cart. When this has a value (non-zero), the component shows the "points applied" view instead of the default banner. Updated automatically from cart updates.    | `number \| string` |         |
| `prizeTitle`     | `prize-title`     | The title of the exchanged prize, shown in the "points applied" view. Updated automatically from cart updates.                                                                                                              | `string`           |         |
| `requireEmail`   | `require-email`   | Does the merchant require registration with email & mobile **Deprecated:** Not read by the component, so it has no effect. It will be removed in the next major version.                                                    | `boolean`          | `false` |

## Methods [#methods]

Call these on the element or a React ref.

### `close() => Promise<HTMLElement>` [#close--promisehtmlelement]

Closes the loyalty popup.

Returns `Promise<HTMLElement>`: Promise that resolves when the popup has closed.

### `exchangeLoyaltyPoint() => Promise<void>` [#exchangeloyaltypoint--promisevoid]

Exchanges points for the prize the customer has currently selected in the popup (no argument). On success the confirmation popup closes,
and on the cart page a "free product" prize reloads the page. On failure an error notification is shown.

### `open() => Promise<any>` [#open--promiseany]

Opens the loyalty popup and loads the loyalty program (the prizes). If the visitor is not logged in, dispatches `login::open` instead and does not open the popup.

Returns `Promise<any>`: Promise that resolves once the program has been loaded (or the load has failed and the popup shows the error).

### `resetExchange() => Promise<any>` [#resetexchange--promiseany]

Cancels the prize that was already exchanged in the cart, which gives the points back.

Returns `Promise<any>`: Promise that resolves when the reset request has finished.

## Slots [#slots]

| Slot                    | Description                                                                                                                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `points-applied-widget` | Widget to show information about the already exchanged points. It should have it's own resetting action and call the `resetExchange` method. If not provided, it will use the default value. |
| `widget`                | When used, will activate the component and needs to emit `loyalty::open` event to open the modal. If not provided the default value will be used.                                            |

## Related [#related]

Renders: [`<salla-placeholder>`](https://docs.salla.dev/twilight/react/web-components/salla-placeholder), [`<salla-button>`](https://docs.salla.dev/twilight/react/web-components/salla-button), [`<salla-list-tile>`](https://docs.salla.dev/twilight/react/web-components/salla-list-tile), [`<salla-modal>`](https://docs.salla.dev/twilight/react/web-components/salla-modal), [`<salla-skeleton>`](https://docs.salla.dev/twilight/react/web-components/salla-skeleton), [`<salla-tabs>`](https://docs.salla.dev/twilight/react/web-components/salla-tabs), [`<salla-tab-header>`](https://docs.salla.dev/twilight/react/web-components/salla-tab-header), [`<salla-tab-content>`](https://docs.salla.dev/twilight/react/web-components/salla-tab-content), [`<salla-slider>`](https://docs.salla.dev/twilight/react/web-components/salla-slider).