> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Subscription alert

Status-aware alert banners that surface the right message based on subscription state.

---

## What it does

A focused alert banner that picks the right message based on subscription state. Pass the subscription, and the component renders the relevant alert. It supports:

- Payment failed
- Canceling or pausing at period end
- Canceled or paused, including resume date
- Trial ending

Returns `null` for healthy states, so it's safe to drop in unconditionally.

## When to use

- You want to alert subscribers to actionable conditions, like updating their payment method.
- You're rendering alongside the [subscription status card](https://developer.paddle.com/sdks/components/subscription-status-card.md) component to surface state changes prominently.
- You need consistent messaging without writing custom logic for every subscription state combination.

**Registry:** [`https://developer.paddle.com/r/subscription-alert.json`](https://developer.paddle.com/r/subscription-alert.json)

## Install

```bash
npx shadcn@latest add @paddle/subscription-alert
```

Also runnable with `pnpm dlx shadcn@latest add @paddle/subscription-alert` or `yarn dlx shadcn@latest add @paddle/subscription-alert`.

## Props

- **subscription** (SubscriptionAlertData): Subscription state. The component derives the right alert (past-due, paused, trial ending, scheduled change, etc.) automatically — and returns null for healthy states, so it's safe to render unconditionally. For past-due alerts, include updatePaymentMethodUrl on the subscription object to surface the recovery CTA.
- **onDismiss** (() => void): Render the alert with a dismiss button. Persist dismissal in your own layer if you want it to stick across reloads.
- **className** (string): Extra Tailwind classes applied to the root element.