Skip to main content

Error State

errorState configures the built-in error UI for the content zone. Activate it by setting status: 'error' on ContentConfig.

Three severity styles are available — error, warning, info — with optional retry support. A full custom renderer override is also available.

How it works​

Set status: 'error' to activate. Widgemo renders the error UI instead of data content. The error payload is available in config.error and passed to any message function or custom renderer. Set errorState.enabled: false to suppress the built-in error UI while keeping status: 'error'.

zones: {
  content: {
    status: 'error',
    error: thrownError,
    errorState: {
      message: 'Failed to load team data.',
      severity: 'error',
      retry: { label: 'Try again', onRetry: refetch },
    },
    mode: 'table',
    item: { fields: […], layout: { type: 'auto' } },
  },
},

Severity: error (default)​

Default error severity — red background, with a retry button.

Team Directory
Failed to load team data.

Severity: warning​

Warning severity — amber background. Useful for partial data or degraded state.

Team Directory
Showing cached data — live sync unavailable.

Severity: info​

Info severity — blue background. Useful for empty states or expected no-data conditions.

Team Directory
No data available for this period.

Dynamic message​

The message field accepts a function that receives the error payload:

errorState: {
  message: (error) => error instanceof Error ? error.message : 'An unexpected error occurred.',
  severity: 'error',
  retry: { label: 'Reload', onRetry: refetch },
},

errorState options​

OptionTypeDefaultEffect
enabledbooleantrueSet to false to suppress built-in error UI while keeping status: 'error'.
messagestring | (error) => string'An error occurred'Error message text. The function receives config.error.
severity'error' | 'warning' | 'info''error'Controls the color scheme of the built-in error card.
retryboolean | { label?, onRetry? }unsettrue enables the retry button but requires errorState.retry.onRetry or the top-level onRetry prop. Object form allows a custom label.
renderer(props) => ReactNodeunsetFull custom error UI. When provided, overrides all built-in rendering.

Custom renderer​

When renderer is provided it takes full control of the error UI — built-in severity rendering is bypassed entirely.

renderer: (props: {
  error:       unknown;
  message?:    string;
  severity?:   'info' | 'warning' | 'error';
  retry?:      () => void;      // backward-compatible alias
  onRetry?:    () => void;
  retryLabel?: string;
  showRetry?:  boolean;
}) => ReactNode

Retry wiring​

SetupResult
retry: { onRetry: fn }Button always shown; calls fn
retry: true + top-level onRetry propTop-level prop is injected as the callback
retry: true without any onRetryButton is not shown (no callback to wire)
retry: falseButton never shown, even when top-level onRetry is provided

For the full onRetry precedence rules, see Widgemo Props — onRetry precedence.

See Also​