@kelviq/react-promotions-ui

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

Installation

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.

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

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.

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)

<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.

<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.

<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., .).

<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., $, €, ₹).

<KQPriceCurrencySymbol />

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

KQPriceCurrencyCode

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

<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:

<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 [email protected].