UpgradeNudge

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

NudgeTrigger

required

The nudge trigger data, typically from the checkUsage() API response.

Show child attributes

'usage_threshold' | 'feature_access' | 'time_based' | 'custom'

What triggered the nudge.

string

Feature key that triggered the nudge.

number

Usage threshold percentage.

number

Actual usage percentage.

object

Show child attributes

string

Nudge title

string

Nudge description

string

Call-to-action button text

object

Show child attributes

string

Plan ID

string

Price ID for checkout

string

Plan name

object

Amount, currency, interval

string[]

Key benefits

'banner' | 'toast' | 'modal'

default:"'banner'"

Display style:

banner — Top banner, non-intrusive
toast — Bottom-right notification
modal — Centered dialog, more prominent

number

default:"0"

Auto-dismiss after N milliseconds. 0 means no auto-dismiss.

(priceId: string) => void

Called when the user clicks the upgrade button.

() => void

Called when the user dismisses the nudge.

'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
      }}
    />
  );
}

Getting Started

Components

Hooks

Advanced

Import

Basic usage

Props

Example: Auto-check and show nudge

​Import

​Basic usage

​Props

​Example: Auto-check and show nudge

Import

Basic usage

Props

Example: Auto-check and show nudge