Habit Smartlink React Component

A React component for integrating Habit Smartlink into your application.

Table of Contents

• Installation
• Usage
• Props
• Default Styles
• Auto-Resize Behavior
• Scroll Behavior
• Issues

Installation

npm install @habit.analytics/habit-smartlink-reactcomponent

Usage

import { SmartlinkComponent } from '@habit.analytics/habit-smartlink-reactcomponent';

const prePaymentMethod = async (quoteId) => {
  // Your application should retrieve payment data for the given quoteId.
  // This is called by the smartlink when it needs a payment_id to proceed.
  return { success: true, payment_id: '12345' };
};

const onPaymentSuccess = (successPaymentData) => {
  // Called when the payment step completes successfully.
  // successPaymentData is a JSON string with the payment result.
  console.log('Payment complete:', successPaymentData);
};

const App = () => (
  <div>
    <h1>Test SmartLink Component</h1>
    <SmartlinkComponent
      hash="sampleHash"
      pin="samplePin"
      prePaymentMethod={prePaymentMethod}
      onPaymentSuccess={onPaymentSuccess}
    />
  </div>
);

export default App;

Props

hash — string (required)

The hash that identifies which payment will be handled. Provided by Habit.

<SmartlinkComponent hash="abc123" prePaymentMethod={prePaymentMethod} />

pin — string (optional)

A PIN value required when the payment link is PIN-protected. Omit if the link has no PIN.

// With PIN protection
<SmartlinkComponent hash="abc123" pin="9876" prePaymentMethod={prePaymentMethod} />

// Without PIN
<SmartlinkComponent hash="abc123" prePaymentMethod={prePaymentMethod} />

prePaymentMethod — (quoteId: string) => Promise<{ success: boolean; payment_id: string }> (required)

Called by the smartlink when it needs your application to create or retrieve a payment. Receives a quoteId string and must return a promise resolving to { success, payment_id }.

If this function throws or returns success: false, the smartlink is notified of the failure and can present an error to the user.

// Successful case
const prePaymentMethod = async (quoteId) => {
  const payment = await myApi.createPayment(quoteId);
  return { success: true, payment_id: payment.id };
};

// Error case — the smartlink will receive the error message
const prePaymentMethod = async (quoteId) => {
  try {
    const payment = await myApi.createPayment(quoteId);
    return { success: true, payment_id: payment.id };
  } catch (err) {
    return { success: false, payment_id: '' };
  }
};

onPaymentSuccess — (successPaymentData: string) => void (optional)

Called when the payment step completes successfully inside the smartlink. successPaymentData is a JSON string containing the payment result returned by the smartlink.

// Redirect after success
const onPaymentSuccess = (successPaymentData) => {
  const data = JSON.parse(successPaymentData);
  window.location.href = `/confirmation?id=${data.payment_id}`;
};

// Display a success message
const onPaymentSuccess = (successPaymentData) => {
  setStatus('Payment completed!');
};

customStyle — React.CSSProperties (optional)

Overrides or extends the default inline styles applied to the iframe. Any valid CSS property can be passed. These are merged on top of the default styles.

// Override width only
<SmartlinkComponent
  hash="abc123"
  prePaymentMethod={prePaymentMethod}
  customStyle={{ width: '100%' }}
/>

// Full custom size with a border
<SmartlinkComponent
  hash="abc123"
  prePaymentMethod={prePaymentMethod}
  customStyle={{ width: '480px', height: '800px', border: '1px solid #e0e0e0', borderRadius: '8px' }}
/>

// Full-width responsive layout
<SmartlinkComponent
  hash="abc123"
  prePaymentMethod={prePaymentMethod}
  customStyle={{ width: '100%', maxWidth: '600px' }}
/>

Default Styles

The iframe renders with the following default styles when no customStyle is provided:

width: 320px;
height: 650px;
overflow: hidden;
display: block;

• width: 320px — matches the minimum supported viewport width of the smartlink content.
• height: 650px — initial height before the first resize message is received.
• overflow: hidden — prevents internal scrollbars; height is kept in sync automatically (see below).
• display: block — removes the inline baseline gap that iframes add by default.

Any property passed via customStyle is merged on top of these defaults and takes precedence.

Auto-Resize Behavior

The smartlink iframe sends resize messages as the content height changes (e.g. between payment steps). The component listens for these messages and automatically updates the iframe's height in real time, so the host page never needs to scroll inside the iframe.

This happens transparently — no extra configuration is required. The height: 650px default is only the initial value and will be replaced as soon as the first resize message arrives.

Scroll Behavior

The iframe's overflow is set to hidden and cannot scroll internally. Instead, the iframe height grows to match its content via the auto-resize behavior described above. If the iframe becomes taller than the viewport, normal page scroll applies on the host page.

Issues

If you find a bug or have any doubts, please report to the Habit contact who is already in touch with you.