npm package: @kelviq/react-promotions-ui
Description: A React SDK for integrating Kelviq dynamic pricing and promotional banners directly into your React application.
Latest version: 0.0.2


# @kelviq/react-promotions-ui

A React SDK for integrating Kelviq dynamic pricing and promotional banners directly into your React application.

## Installation

```bash
npm install @kelviq/react-promotions-ui
```

## Getting Started

Wrap your app with the `KQProvider` at the root level. This sets up the context and fetches promotion data from the Kelviq API.

```tsx
import { KQProvider } from '@kelviq/react-promotions-ui';

function App() {
  return (
    <KQProvider
      promotionId="YOUR_PROMOTION_ID"
      accessToken="YOUR_ACCESS_TOKEN"
    >
      {/* Your app components */}
    </KQProvider>
  );
}
```

### Provider Attributes

| Attribute | Type | Default | Description |
| --------- | ---- | ------- | ----------- |
| `promotionId` | string | `''` | The promotion ID to fetch data for. |
| `accessToken` | string | `''` | Access token sent as `Authorization: Bearer` header. |
| `kqIdentifier` | string | `''` | Optional Kelviq identifier for the request. |
| `environment` | string | `'production'` | Set to `'sandbox'` to use the sandbox API. |
| `baseCurrencyCode` | string | `'USD'` | Base currency code. Currency formatting uses this code. |
| `baseCurrencySymbol` | string | `'$'` | Base currency symbol for display purposes. |
| `config` | object | `{}` | Advanced config: `apiUrl`, `onError`, `maxRetries`, `timeout`. |

---

## Components

### `KQBanner`

Displays a location-aware promotional banner. The banner message supports template variables that are automatically replaced with real data:

- `{country}` — visitor's country name
- `{country_flag}` — country flag image (loaded from CDN)
- `{coupon_code}` — the discount coupon code
- `{discount_percentage}` — the discount percentage

```tsx
import { KQBanner } from '@kelviq/react-promotions-ui';

<KQBanner />

{/* With custom style overrides */}
<KQBanner
  backgroundColor="#1a1a2e"
  fontColor="#eaeaea"
  borderRadius="8px"
  fontSize="14px"
  addCloseIcon={true}
  className="custom-banner"
  onClose={() => console.log('Banner closed')}
/>
```

| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| `backgroundColor` | string | *(from API)* | Banner background color. |
| `fontColor` | string | *(from API)* | Banner text color. |
| `borderRadius` | string | *(from API)* | Banner border radius. |
| `fontSize` | string | *(from API)* | Banner font size. |
| `unStyled` | boolean | *(from API)* | If `true`, no default styles are injected. |
| `addCloseIcon` | boolean | *(from API)* | Show a close button on the banner. |
| `className` | string | `''` | Custom CSS class name. |
| `onClose` | function | — | Callback when the banner is closed. |

---

### `KQPriceFormatted`

Displays a formatted discounted price based on the visitor's location.

```tsx
import { KQPriceFormatted } from '@kelviq/react-promotions-ui';

{/* Discounted price */}
<KQPriceFormatted price={99.99} />

{/* With decimals */}
<KQPriceFormatted price={99.99} showDecimal={true} />

{/* Currency code display */}
<KQPriceFormatted price={99.99} currencyDisplay="code" />
```

#### Original + Discounted (Strikethrough)

```tsx
<KQPriceFormatted
  price={99.99}
  displayPrice={99.99}
  isOriginalDisplay={true}
  showDecimal={true}
/>
<KQPriceFormatted price={99.99} showDecimal={true} />
```

| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| `price` | number | — | **Required.** The product price. |
| `displayPrice` | number | — | The price shown for original display (used with `isOriginalDisplay`). |
| `isOriginalDisplay` | boolean | `false` | Renders as strikethrough original price for comparison. |
| `className` | string | `''` | Custom CSS class name. |
| `currencyDisplay` | `'symbol' \| 'code' \| 'name'` | `'symbol'` | How the currency is displayed. |
| `showDecimal` | boolean | `false` | Whether to show decimal digits. |
| `minimumDecimalDigits` | number | `2` | Minimum decimal digits when `showDecimal` is `true`. |
| `maximumDecimalDigits` | number | `2` | Maximum decimal digits (max 2). |

---

## Granular Price Components

Use these components individually to build custom price layouts with full styling control.

### `KQPriceInteger`

Displays just the integer part of the price.

```tsx
<KQPriceInteger price={99.99} />
```

| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| `price` | number | — | **Required.** The product price. |
| `className` | string | `''` | Custom CSS class name. |

---

### `KQPriceDecimal`

Displays just the decimal portion.

```tsx
<KQPriceDecimal price={99.99} />
```

| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| `price` | number | — | **Required.** The product price. |
| `className` | string | `''` | Custom CSS class name. |
| `minimumDecimalDigits` | number | `2` | Minimum decimal digits. |
| `maximumDecimalDigits` | number | `2` | Maximum decimal digits (max 2). |

---

### `KQPriceDecimalSeparator`

Renders the decimal separator (e.g., `.`).

```tsx
<KQPriceDecimalSeparator price={99.99} />
```

| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| `price` | number | — | **Required.** The product price. |
| `className` | string | `''` | Custom CSS class name. |

---

### `KQPriceCurrencySymbol`

Renders the currency symbol (e.g., $, €, ₹).

```tsx
<KQPriceCurrencySymbol />
```

| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| `className` | string | `''` | Custom CSS class name. |

---

### `KQPriceCurrencyCode`

Renders the currency code (e.g., USD, EUR, INR).

```tsx
<KQPriceCurrencyCode />
```

| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| `className` | string | `''` | Custom CSS class name. |

---

### Custom Price Layout Example

Combine granular components to build a fully custom price display:

```tsx
<div className="custom-price-display">
  <KQPriceCurrencySymbol />
  <KQPriceInteger price={99.99} />
  <KQPriceDecimalSeparator price={99.99} />
  <KQPriceDecimal price={99.99} />
  <KQPriceCurrencyCode />
</div>
```

---

## Support

Need help or have questions? Reach out to us at **[hi@kelviq.com](mailto:hi@kelviq.com)**.