Oops UI - Beautiful Error Pages for Laravel

Introduction

Oops UI is a powerful Laravel package designed to replace the default, often sterile error pages with beautiful, branded, and informative experiences. It works out of the box with zero configuration and supports both high-fidelity HTML templates and clean JSON responses for API-driven applications.

Key Features

✓ 11 Beautiful Pre-built Templates
✓ Seamless App Layout Integration
✓ Automatic Dark Mode Support
✓ Fully Customizable Footers
✓ Intelligent API Request Detection
✓ Zero Configuration Startup
✓ Comprehensive Localization Support
✓ Responsive Mobile-first Design

Why Choose Oops UI?

🚀

Zero Setup

Works immediately after installation.

🎨

11 Templates

Sleek designs for every brand style.

📱

Responsive

Pixels perfect on every screen size.

🌙

Dark Mode

Native theme switching support.

🎯

App Layout

Wrap errors in your existing layout.

📄

Footer Info

Add menus, social and contact info.

🔌

API Support

Auto-detects JSON requests.

🌍

Localization

Ready for worldwide use.

Installation

Install the package via Composer into your Laravel application:

composer require biplove/oops-ui

The package uses Laravel's package discovery to register itself automatically. No further steps are needed for basic functionality.

Quick Start

Immediately after installation, visit any non-existent URL (e.g., /this-is-a-404-test) on your site to see the Oops UI default error page in action.

Optional: Publish Configuration

To customize templates, colors, and content, publish the configuration file:

php artisan oops:install

Quick Customization Examples

1. Change Template

Edit config/oops-ui.php:

'settings' => [
    'default_template' => 'modern', // Use 'modern' for all errors
],

2. Enable Dark Mode

'settings' => [
    'theme' => 'dark', // Enable system-wide dark mode
],

Configuration

Basic Configuration

The config/oops-ui.php file is the central hub for all customizations. It is organized into several high-level arrays:

// config/oops-ui.php

'settings' => [ ... ], // Global appearance

'errors' => [ ... ], // Specific error settings

'api_error_mode' => 'auto', // JSON vs HTML

Template Selection

You can set a global template or override it for specific HTTP status codes.

Per-Error Override

'errors' => [
    '404' => [
        'template' => 'illustration', // 404 uses illustration
    ],
    '500' => [
        'template' => 'minimal',      // 500 uses minimal
    ],
],

App Layout Integration

Maintain consistent branding by wrapping error content inside your application's main layout file.

Requirements:

Set app_layout (e.g., 'layouts.app')
Set app_layout_section (e.g., 'content')
Ensure the layout file exists
Use the @oopsError directive in your layout

Example Layout usage:

<!-- resources/views/layouts/app.blade.php -->
<main>
    @oopsError('content')
</main>

Customize Colors, Typography & Card

The colors, typography, and card arrays allow you to customize the appearance of the 'layout' template:

Colors

'settings' => [
    'colors' => [
        'background' => '#f8fafc',
        'card' => '#ffffff',
        'text' => '#0f172a',
        'muted' => '#475569',
        'border' => '#e2e8f0',
        'accent' => '#0f766e',
        'accent_soft' => '#ccfbf1',
    ],
],

Typography

'typography' => [
    'font_family' => '"Segoe UI", sans-serif',
    'title_size' => '30px',
    'message_size' => '16px',
],

Card Settings

'card' => [
    'max_width' => '640px',
    'padding' => '28px',
    'border_radius' => '16px',
],

Footer Configuration

Enhance your error pages with a professional footer. You can customize branding, menus, social links, and the About section.

'footer' => [
    'enabled' => true,
    'company_name' => 'Your Brand Name',
    'copyright_text' => 'All rights reserved © {current_year}', // Auto-updates the year
    'show_year' => true,
    
    'menu_title' => 'Navigation',
    'menu_items' => [
        ['text' => 'Home', 'url' => '/'],
        ['text' => 'Contact', 'url' => '/contact'],
    ],

    'contact_title' => 'Get in Touch',
    'contact_info' => [
        'email' => 'support@brand.com',
    ],

    'social_title' => 'Follow Us',
    'social_links' => [
        ['platform' => 'github', 'url' => '...'],
        ['platform' => 'twitter', 'url' => '...'],
    ],

    'custom_title' => 'About Oops UI',
    'custom_text' => 'Modern error handling for Laravel applications.',
],

💡 Pro Tip:

Use the {current_year} keyword in copyright_text to dynamically resolve the current year in your error pages.

Custom Error Pages Configuration

Customize individual error pages by configuring titles, messages, buttons, and templates for specific error codes.

'404' => [
    'template' => 'modern',
    'title' => 'Page Not Found',
    'message' => 'The page you are looking for does not exist.',
    'buttons' => [
        ['text' => 'Go Home', 'url' => '/', 'style' => 'primary'],
        ['text' => 'Go Back', 'url' => 'back', 'style' => 'secondary'],
    ],
    'image' => [
        'url' => '/images/404.svg',
        'alt' => 'Not found illustration',
    ],
],

Special URL Keywords:

'retry' or 'current' - Reloads the current page
'back' - Navigates to the previous page
Regular URL (e.g., '/') - Custom navigation

API Error Mode

Control how errors are returned for API requests. The package can automatically detect API requests or be forced into specific modes.

'api_error_mode' => 'auto',
'api_base_path' => 'api',

auto

Checks Accept/Content-Type headers for JSON.

json

Always returns JSON for API base path routes.

html

Always returns HTML error pages.

Available Templates

layout

Default card-based design with center alignment

modern

Sleek gradient designs and large error codes

minimal

Clean, distraction-free monospace typography

classic

Professional traditional serif design

gradient

Vibrant, colorful full-screen gradients

illustration

Playful SVG illustrations for every error

neon

Cyberpunk inspired glow and sharp lines

glass

Modern glassmorphism and blur effects

terminal

Retro console style for tech enthusiasts

animated

Engaging CSS-driven animations

split

Modern split-screen informational design

API Error Responses

For API requests, Oops UI returns a structured JSON payload instead of an HTML page. This ensures your mobile apps and frontend SPAs can handle errors gracefully.

JSON Response Format

{
    "error": true,
    "status": 404,
    "title": "Page Not Found",
    "message": "The page you are looking for does not exist."
}

Validation Errors (422)

Special handling is included for validation failures, echoing your Laravel validation data:

{
    "error": true,
    "status": 422,
    "errors": {
        "email": ["The email field is required."],
        "password": ["The password must be 8+ characters."]
    }
}

Troubleshooting

Changes not reflecting?

If you update your configuration but still see the old design, it's likely due to Laravel's configuration caching. Run these commands:

php artisan config:clear && php artisan view:clear

API returning HTML?

Ensure your request includes the Accept: application/json header, or explicitly set your api_base_path in the configuration to match your API version.