ErrorState

Error display with variant-specific messaging, retry actions, and expandable error details.

iOSAndroid

Preview ErrorState 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-error-state

Usage

import { ErrorState } from '@/components/docyrus-native/error-state';

<ErrorState variant="network" onRetry={() => refetch()} />

<ErrorState
  variant="server"
  errorCode={500}
  errorMessage="Internal Server Error: Connection refused at db:5432"
  onRetry={() => refetch()}
  onBack={() => navigation.goBack()}
/>

API Reference

Prop	Type	Default	Description
`variant`	`'default' \| 'network' \| 'server' \| 'timeout' \| 'not-found' \| 'forbidden' \| 'maintenance'`	`'default'`	Preset variant with default icon, title, and description
`icon`	`ReactNode`	—	Custom icon to display (overrides variant emoji)
`title`	`string`	—	Custom title (overrides variant default)
`description`	`string \| ErrorObject`	—	Custom description or error object with message/code
`errorMessage`	`string`	—	Detailed error message shown in expandable details section
`errorCode`	`string \| number`	—	Error code displayed as a badge
`onRetry`	`() => void`	—	Retry button press handler
`retryLabel`	`string`	`'Try again'`	Custom retry button label
`isRetrying`	`boolean`	`false`	Show retrying state with spinner animation
`onBack`	`() => void`	—	Back button press handler
`backLabel`	`string`	`'Go back'`	Custom back button label
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Component size
`className`	`string`	—	Additional CSS classes
`accessibilityLabel`	`string`	—	Accessibility label override

Translation Keys

Built-in copy is read through useUiTranslation() — provide these keys via <UiTranslationProvider>. Without a provider the English fallback is shown.

Key	English fallback	Used for
`ui.errorState.defaultTitle`	Something went wrong	Title (`title` prop wins)
`ui.errorState.defaultDescription`	An unexpected error occurred. Please try again.	Description (`description` prop wins)
`ui.errorState.networkTitle`	Connection lost	Title (`title` prop wins)
`ui.errorState.networkDescription`	Please check your internet connection and try again.	Description (`description` prop wins)
`ui.errorState.serverTitle`	Server error	Title (`title` prop wins)
`ui.errorState.serverDescription`	Our servers are having trouble. Please try again later.	Description (`description` prop wins)
`ui.errorState.timeoutTitle`	Request timed out	Title (`title` prop wins)
`ui.errorState.timeoutDescription`	The server took too long to respond. Please try again.	Description (`description` prop wins)
`ui.errorState.notFoundTitle`	Not found	Title (`title` prop wins)
`ui.errorState.notFoundDescription`	The requested resource could not be found.	Description (`description` prop wins)
`ui.errorState.forbiddenTitle`	Access denied	Title (`title` prop wins)
`ui.errorState.forbiddenDescription`	You don't have permission to access this resource.	Description (`description` prop wins)
`ui.errorState.maintenanceTitle`	Under maintenance	Title (`title` prop wins)
`ui.errorState.maintenanceDescription`	We're performing scheduled maintenance. Please check back soon.	Description (`description` prop wins)
`ui.errorState.errorPrefix`	Error	Prefix before the error code
`ui.errorState.showDetails`	Show details	Details toggle
`ui.errorState.hideDetails`	Hide details	Details toggle
`ui.errorState.retry`	Try again	Retry button (`retryLabel` prop wins)
`ui.errorState.retrying`	Retrying...	Retry button while `isRetrying`
`ui.errorState.back`	Go back	Back button (`backLabel` prop wins)

Type Exports

Type	Description
`ErrorStateProps`	Props for ErrorState component
`ErrorStateVariant`	`'default' \| 'network' \| 'server' \| 'timeout' \| 'not-found' \| 'forbidden' \| 'maintenance'`
`ErrorStateSize`	`'sm' \| 'md' \| 'lg'`