RateLimitBanner

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

iOSAndroid

Preview RateLimitBanner on your device

Scan with Expo Go

Download Expo Go, then scan the QR code to preview native components.

Installation

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

Required Packages(2 packages)

pnpm add react-native-reanimated react-native-safe-area-context

Usage

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

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

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

Toast mode

<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'`