# rn-rate-limit-banner
URL: /docs/native/docyrus/rate-limit-banner

Animated banner for displaying API rate limiting and circuit breaker states with retry countdown.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-rate-limit-banner
```

**Dependencies:**
- [react-native-reanimated](https://www.npmjs.com/package/react-native-reanimated)
- [react-native-safe-area-context](https://www.npmjs.com/package/react-native-safe-area-context)

## Usage

```tsx
import { RateLimitBanner } from '@/components/docyrus-native/rate-limit-banner';

<RateLimitBanner
  visible={isBlocked}
  blockReason="rate_limited"
  retryAfterSeconds={retryAfter}
  onRetry={() => retryRequest()}
  onDismiss={() => setBlocked(false)}
/>
```

### Modal mode

```tsx
<RateLimitBanner
  visible={isBlocked}
  mode="modal"
  blockReason="circuit_open"
  retryAfterSeconds={30}
  onRetry={() => retryRequest()}
  onReload={() => reloadApp()}
/>
```

### Toast mode

```tsx
<RateLimitBanner
  visible={isBlocked}
  mode="toast"
  blockReason="rate_limited"
  retryAfterSeconds={5}
  onDismiss={() => dismiss()}
/>
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `visible` | `boolean` | — | Whether the banner is visible |
| `blockReason` | `'rate_limited' \| 'circuit_open'` | `'rate_limited'` | Why the request was blocked |
| `retryAfterSeconds` | `number` | `0` | Seconds remaining before retry is allowed (0 = ready) |
| `mode` | `'banner' \| 'modal' \| 'toast'` | `'banner'` | Display mode |
| `rateLimitTitle` | `string` | `'Too Many Requests'` | Title when rate limited |
| `rateLimitMessage` | `string` | `'Please slow down...'` | Message when rate limited |
| `circuitOpenTitle` | `string` | `'Service Temporarily Unavailable'` | Title when circuit is open |
| `circuitOpenMessage` | `string` | `'We are experiencing issues...'` | Message when circuit is open |
| `retryButtonText` | `string` | `'Try again'` | Retry button label |
| `reloadButtonText` | `string` | `'Reload App'` | Reload button label |
| `showReloadButton` | `boolean` | `true` | Show reload action button |
| `autoHideDelay` | `number` | `2000` | Auto-hide delay after recovery (ms), 0 to disable |
| `onRetry` | `() => void` | — | Retry button handler |
| `onReload` | `() => void` | — | Reload button handler |
| `onDismiss` | `() => void` | — | Dismiss/close handler |
| `className` | `string` | — | Additional CSS classes |

## Display Modes

| Mode | Description |
|------|-------------|
| `banner` | Full-width top banner with slide-in animation. Shows title, message, countdown, retry and reload buttons. |
| `modal` | Centered modal overlay with icon, title, message, countdown badge, and action buttons. |
| `toast` | Bottom floating toast with compact layout, title, countdown, and dismiss button. |

## Type Exports

| Type | Description |
|------|-------------|
| `RateLimitBannerProps` | Props for RateLimitBanner component |
| `RateLimitBannerMode` | `'banner' \| 'modal' \| 'toast'` |
| `RateLimitBlockReason` | `'rate_limited' \| 'circuit_open'` |