@molecule/app-loyalty-tier-badge-react

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Bronze/Silver/Gold/Platinum loyalty tier badge with optional progress bar to the next tier.

Exports:

• <LoyaltyTierBadge> — colored tier glyph + label; when BOTH points and nextTierThreshold are set (and a next tier exists) it also renders a progress bar plus an "X to next tier" readout; platinum shows "Top tier reached" instead. Props: tier, points?, nextTierThreshold?, tierLabel? / nextTierLabel? (override the translated names for branded programs, e.g. "Member" / "Elite"), size? ('sm' | 'md' | 'lg'), dataMolId?, className?.
• LoyaltyTier, LoyaltyTierBadgeProps types; computeProgress() and nextTierOf() helpers.

Quick Start

import { LoyaltyTierBadge } from '@molecule/app-loyalty-tier-badge-react'

;<LoyaltyTierBadge tier="gold" points={42_000} nextTierThreshold={75_000} />

Type

feature

Installation

npm install @molecule/app-loyalty-tier-badge-react @molecule/app-i18n @molecule/app-react @molecule/app-ui react
npm install -D @types/react

API

Interfaces

LoyaltyTierBadgeProps

Props for {@link LoyaltyTierBadge}.

interface LoyaltyTierBadgeProps {
  /** Current tier. */
  tier: LoyaltyTier
  /**
   * Member's current points / nights / qualifying activity in the tier
   * unit. Optional; when present and `nextTierThreshold` is also given the
   * badge renders a progress bar and "X to next tier" readout.
   */
  points?: number
  /**
   * Threshold (in the same unit as `points`) at which the next tier is
   * earned. Combined with `points` to compute progress.
   */
  nextTierThreshold?: number
  /** Override the auto-derived next-tier label (e.g. "Diamond"). */
  nextTierLabel?: string
  /** Override the displayed tier label (defaults to translated tier name). */
  tierLabel?: string
  /** Display size. */
  size?: 'sm' | 'md' | 'lg'
  /** `data-mol-id` attribute for AI-agent selectors. */
  dataMolId?: string
  /** Extra classes appended via the ClassMap `cn()` helper. */
  className?: string
}

Types

LoyaltyTier

Standard loyalty tier rungs.

type LoyaltyTier = 'bronze' | 'silver' | 'gold' | 'platinum'

Functions

computeProgress(points, threshold)

Compute progress (0–1) toward the next tier given current points + threshold.

function computeProgress(points?: number, threshold?: number): number

• points — Current points balance.
• threshold — Points needed to reach the next tier.

Returns: Clamped 0–1 progress ratio.

LoyaltyTierBadge(props)

Loyalty tier badge — renders a colored glyph + tier label + (optional) "X / Y to next tier" progress bar. Used by hotel-booking, online-store, and travel-booking flagship loyalty programs.

Tier glyph colors are always the standard metallic accents (fixed per-tier hex values — theme tokens are not consulted for the glyph); pass tierLabel / nextTierLabel to override the translated defaults for branded programs (e.g. "Member" / "Elite").

function LoyaltyTierBadge({
  tier,
  points,
  nextTierThreshold,
  nextTierLabel,
  tierLabel,
  size = 'md',
  dataMolId,
  className,
}: LoyaltyTierBadgeProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>

• props — Component props.

Returns: The rendered tier badge.

nextTierOf(tier)

Resolve the next tier name (lowercase) given the current tier. Returns null when the member is already at the highest tier.

function nextTierOf(tier: LoyaltyTier): LoyaltyTier | null

• tier — Current tier.

Returns: The next-tier name or null if at the top.

Injection Notes

Requirements

Peer dependencies:

• @molecule/app-i18n ^1.0.1
• @molecule/app-react ^1.0.1
• @molecule/app-ui ^1.0.1
• react ^18.0.0 || ^19.0.0

Runtime Dependencies

• @molecule/app-i18n

• @molecule/app-react

• @molecule/app-ui

• react

• The tier glyph accent is ALWAYS a fixed metallic hex per tier (bronze / silver / gold / platinum) — it does not read theme tokens; only the border and secondary text use --mol-color- variables (with light-theme fallbacks).

• Labels route through t() under the loyaltyTierBadge. prefix. The companion @molecule/app-locales-loyalty-tier-badge bond currently ships only group and progress — the tier names, remaining, and topTier strings fall back to English everywhere until the bond gains those keys (or pass tierLabel / nextTierLabel yourself).

• points / nextTierThreshold must share a unit (points, nights, spend); progress is clamped to 0–1.

Translations

Translation strings are provided by @molecule/app-locales-loyalty-tier-badge.