Error Pages

Introduction

Error page component collection providing user-friendly pages for common HTTP error status codes. Through unified design style and clear information communication, help users understand error causes and provide solutions.

Component features:

• 🎨 Unified Design - All error pages adopt consistent design style
• 🌐 Multiple Error Types - Support 404, 403, 500, 503 and other common errors
• 🔧 Debug Friendly - Optional debug information display for development and troubleshooting
• 📱 Responsive Design - Adapts to different screen sizes
• 🎯 User Guidance - Provides useful action suggestions and navigation links

Basic Usage

The simplest example using a 404 error page:

              ---
/**
 * @component Error404.Basic
 *
 * @description
 * 基础的404错误页面示例，展示最简单的404错误页面用法。
 */
import { Error404 } from '@coffic/cosy-ui';
---

<Error404 />

            

Error Page Types

403 Forbidden

Used to display messages when users don’t have permission to access resources:

              ---
/**
 * @component Error403.Basic
 *
 * @description
 * 基础的403禁止访问错误页面示例。
 */
import { Error403 } from '@coffic/cosy-ui';
---

<Error403 />

            

500 Internal Server Error

Used to display messages when the server encounters internal errors:

              ---
/**
 * @component Error500.Basic
 *
 * @description
 * 基础的500服务器内部错误页面示例。
 */
import { Error500 } from '@coffic/cosy-ui';
---

<Error500 />

            

503 Service Unavailable

Used to display messages when service is temporarily unavailable, especially for maintenance mode:

              ---
/**
 * @component Error503.Maintenance
 *
 * @description
 * 503服务不可用错误页面的维护模式示例，展示系统维护时的页面。
 */
import { Error503 } from '@coffic/cosy-ui';
---

<Error503
  maintenanceMode={true}
  estimatedRecovery="2024-12-25 10:00"
  statusPageUrl="https://status.example.com"
  debugKVs={{
    reason: '系统升级',
    startTime: '2024-12-25 08:00',
    version: 'v2.1.0',
  }}
/>

            

Universal Error Page

Using the ErrorPage component can automatically select the appropriate error page based on error code:

---
import { ErrorPage } from '@coffic/cosy-ui';
---

<!-- Automatically select page based on error code -->
<ErrorPage errorCode={404} />
<ErrorPage errorCode={403} loginUrl="/login" />
<ErrorPage errorCode={500} supportUrl="/support" />
<ErrorPage errorCode={503} maintenanceMode={true} />

Custom Styles

Customize the appearance of error pages using the class property:

              ---
/**
 * @component ErrorPage.CustomStyle
 *
 * @description
 * 错误页面的自定义样式示例，展示如何通过class属性自定义错误页面的样式。
 */
import { Error404 } from '@coffic/cosy-ui';
---

<div
  class="cosy:bg-gradient-to-br cosy:from-purple-50 cosy:to-pink-50 cosy:dark:from-purple-900/20 cosy:dark:to-pink-900/20 cosy:p-8 cosy:rounded-xl">
  <Error404
    debugKVs={{
      customization: '自定义渐变背景',
      style: '紫色到粉色渐变',
      note: '这是一个自定义样式的示例',
    }}
  />
</div>

            

Error Pages Showcase

View a comprehensive display of all error page types:

              ---
/**
 * @component ErrorPage.Showcase
 *
 * @description
 * 展示所有错误页面的组件示例，用于演示和测试不同类型的错误页面。
 */
import { ErrorPage } from '@coffic/cosy-ui';
import { Container, Stack } from '@coffic/cosy-ui';
---

<Container size="lg" padding="lg">
  <Stack gap="xl">
    <div class="cosy:text-center cosy:mb-8">
      <h1 class="cosy:text-3xl cosy:font-bold cosy:mb-4">错误页面展示</h1>
      <p class="cosy:text-base-content/70">
        以下是不同HTTP错误状态码对应的错误页面
      </p>
    </div>

    <!-- 404错误 -->
    <section class="cosy:border cosy:border-base-300 cosy:rounded-lg cosy:p-6">
      <h2 class="cosy:text-xl cosy:font-semibold cosy:mb-4">
        404 - 页面未找到
      </h2>
      <ErrorPage errorCode={404} debugKVs={{ example: 'demo' }} />
    </section>

    <!-- 403错误 -->
    <section class="cosy:border cosy:border-base-300 cosy:rounded-lg cosy:p-6">
      <h2 class="cosy:text-xl cosy:font-semibold cosy:mb-4">403 - 禁止访问</h2>
      <ErrorPage
        errorCode={403}
        loginUrl="/login"
        contactUrl="/contact"
        debugKVs={{ requiredRole: 'admin', currentRole: 'user' }}
      />
    </section>

    <!-- 500错误 -->
    <section class="cosy:border cosy:border-base-300 cosy:rounded-lg cosy:p-6">
      <h2 class="cosy:text-xl cosy:font-semibold cosy:mb-4">
        500 - 服务器内部错误
      </h2>
      <ErrorPage
        errorCode={500}
        supportUrl="/support"
        statusPageUrl="/status"
        debugKVs={{ errorId: 'ERR_2024_001', serverInfo: 'Server-01' }}
      />
    </section>

    <!-- 503错误 -->
    <section class="cosy:border cosy:border-base-300 cosy:rounded-lg cosy:p-6">
      <h2 class="cosy:text-xl cosy:font-semibold cosy:mb-4">
        503 - 服务不可用
      </h2>
      <ErrorPage
        errorCode={503}
        maintenanceMode={true}
        estimatedRecovery="2024-12-25 10:00"
        statusPageUrl="/status"
        notificationUrl="/notifications"
        debugKVs={{ reason: '系统升级', startTime: '2024-12-25 08:00' }}
      />
    </section>
  </Stack>
</Container>

            

Advanced Usage

Adding Debug Information

All error pages support adding debug information for development and troubleshooting:

<ErrorPage
  errorCode={404}
  debugKVs={{
    reason: 'Route not matched',
    requestedPath: '/some/path',
    timestamp: new Date().toISOString(),
    requestId: 'REQ_2024_001',
  }}
/>

Maintenance Mode Configuration

For 503 errors, you can configure detailed maintenance information:

<ErrorPage
  errorCode={503}
  maintenanceMode={true}
  estimatedRecovery="2024-12-25 10:00"
  statusPageUrl="/status"
  notificationUrl="/notifications"
  debugKVs={{
    reason: 'System upgrade',
    version: 'v2.1.0',
    startTime: '2024-12-25 08:00',
  }}
/>

Permission Error Configuration

For 403 errors, you can provide login and contact links:

<ErrorPage
  errorCode={403}
  loginUrl="/login"
  contactUrl="/contact"
  debugKVs={{
    requiredRole: 'admin',
    currentRole: 'user',
    resource: '/admin/dashboard',
  }}
/>

Props Reference

ErrorPage Props

Individual Error Page Props

Each specific error page component has corresponding props, see JSDoc comments for each component.

Best Practices

1. Use ErrorPage Component - Recommend using ErrorPage instead of individual error page components for better flexibility and maintainability

2. Provide Useful Information - Use debugKVs appropriately to provide debug information, but avoid leaking sensitive information in production

3. Guide User Actions - Provide appropriate action links based on error type:

   • 403 errors: Provide login links and contact information
   • 500 errors: Provide technical support and status page links
   • 503 errors: Provide maintenance information and notification subscription

4. Maintenance Friendly - For 503 errors, provide detailed maintenance information and estimated recovery time

5. Responsive Considerations - Ensure error pages display well on various devices

Style Customization

All error page components follow cosy-ui style specifications:

• Use daisyUI classes as the main style foundation
• Tailwind CSS classes require the cosy: prefix
• Support responsive design, adapting to various screen sizes
• Full support for dark mode switching