Skip to main content

​
Import

import { UpgradeNudge } from "@billingos/sdk";

​
Basic usage

<UpgradeNudge
  trigger={nudgeTrigger}
  style="banner"
  onUpgrade={(priceId) => openCheckout(priceId)}
/>
Displays an upgrade prompt when usage data indicates the user should upgrade. Supports three display styles. Upgrade nudge

​
Props

​
trigger
NudgeTrigger
required
The nudge trigger data, typically from the checkUsage() API response.
​
style
'banner' | 'toast' | 'modal'
default:"'banner'"
Display style:
  • banner — Top banner, non-intrusive
  • toast — Bottom-right notification
  • modal — Centered dialog, more prominent
​
autoDismiss
number
default:"0"
Auto-dismiss after N milliseconds. 0 means no auto-dismiss.
​
onUpgrade
(priceId: string) => void
Called when the user clicks the upgrade button.
​
onDismiss
() => void
Called when the user dismisses the nudge.
​
theme
'light' | 'dark'
Color theme.

​
Example: Auto-check and show nudge

import { UpgradeNudge, useBillingOS } from "@billingos/sdk";
import { useQuery } from "@tanstack/react-query";

function NudgeWrapper() {
  const { client } = useBillingOS();
  const { data } = useQuery({
    queryKey: ["usage-check"],
    queryFn: () => client!.checkUsage(),
    enabled: !!client,
  });

  if (!data?.shouldShowNudge || !data.trigger) return null;

  return (
    <UpgradeNudge
      trigger={data.trigger}
      style="banner"
      onUpgrade={(priceId) => {
        router.push(`/pricing?upgrade=${priceId}`);
      }}
      onDismiss={() => {
        // Optionally track dismissal
      }}
    />
  );
}