README

UmbraUI

Essential UI components library for Laravel applications with Tailwind CSS

UmbraUI provides the most essential UI components for modern web applications with full extensibility, 4 beautiful themes, and seamless Laravel integration. Every component supports custom classes with intelligent Tailwind class merging.

✨ Key Features

• 🎨 4 Color Schemes - neutral, stone, zinc, gray with automatic light/dark mode
• 🔧 Fully Extensible - Override any component styles with custom classes
• 🚀 CLI Commands - Interactive setup and component installation
• ♿ Accessibility First - WCAG compliant components
• 📦 30+ Components - Everything you need for modern web apps

Essential Components

UmbraUI focuses on the most critical components for modern web applications, based on industry standards and popular libraries like shadcn/ui, Tailwind UI, and Chakra UI.

Core Form Components ✅

Navigation & Layout ✅

Data Display ✅

Notifications ✅

Icons

UmbraUI uses Tabler Icons - a beautiful set of 4,900+ free SVG icons designed for web interfaces. All components that require icons come with pre-integrated Tabler icons support for consistency and visual appeal.

{{-- Basic usage --}}
<x-umbra-ui::icons.home />
<x-umbra-ui::icons.user />
<x-umbra-ui::icons.heart />

{{-- Custom colors --}}
<x-umbra-ui::icons.heart class="text-red-500" />
<x-umbra-ui::icons.star class="text-yellow-400" />

{{-- Custom sizes --}}
<x-umbra-ui::icons.home class="w-4 h-4" />
<x-umbra-ui::icons.settings class="w-8 h-8" />

{{-- Combined customization --}}
<x-umbra-ui::icons.bell class="w-6 h-6 text-blue-600" />

📋 Requirements

• PHP 8.1 or higher
• Laravel 10.x or 11.x
• Tailwind CSS 4.x
• Alpine.js 3.x (for interactive components)

📦 Installation

Install via Composer:

composer require ihxnnxs/umbra-ui

Initialize UmbraUI and choose your theme:

php artisan umbra:init

This interactive command will:

• Let you choose from 4 color schemes (neutral, stone, zinc, gray)
• Create components.json configuration
• Set up your theme with CSS variables
• Create the components directory

Add Alpine.js (Required for Interactive Components)

Include Alpine.js in your layout for components like modals, dropdowns, tabs, etc:

<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>

Or install via npm:

npm install alpinejs

Publishing Assets (Optional)

For JavaScript toast notifications:

php artisan vendor:publish --tag=umbra-ui-assets

🚀 Quick Start

Theme Customization

Every component supports custom classes with intelligent merging:

{{-- Override component styles --}}
<x-umbra-ui::button class="bg-purple-500 hover:bg-purple-600">
    Custom Button
</x-umbra-ui::button>

{{-- Classes are intelligently merged, last wins on conflicts --}}
<x-umbra-ui::badge variant="primary" class="rounded-full">
    Rounded Badge
</x-umbra-ui::badge>

Installing Additional Components

Use the umbra:add command to install components on demand:

# Install a single component
php artisan umbra:add button

# Install multiple components
php artisan umbra:add button input select

# Install all components
php artisan umbra:add --all

Usage

Basic Components

{{-- Buttons --}}
<x-umbra-ui::button>Primary Button</x-umbra-ui::button>
<x-umbra-ui::button type="submit" class="bg-blue-600">Custom Button</x-umbra-ui::button>

{{-- Form Inputs --}}
<x-umbra-ui::input type="email" placeholder="Enter email" />
<x-umbra-ui::textarea placeholder="Your message..." />
<x-umbra-ui::select>
    <option>Choose...</option>
    <option value="1">Option 1</option>
</x-umbra-ui::select>

{{-- Form Controls --}}
<x-umbra-ui::checkbox id="terms" />
<x-umbra-ui::label for="terms">Accept Terms</x-umbra-ui::label>

<x-umbra-ui::radio name="choice" value="a" id="choice-a" />
<x-umbra-ui::label for="choice-a">Choice A</x-umbra-ui::label>

<x-umbra-ui::switch id="notifications" />

Advanced Components

{{-- Form Fields with Validation --}}
<x-field label="Email Address" error="Email is required">
    <x-input type="email" />
</x-field>

<x-field label="Message" helper="Maximum 500 characters">
    <x-textarea />
</x-field>

{{-- Navigation --}}
<x-tabs default-tab="overview">
    <x-tabs.nav>
        <x-tabs.tab value="overview">Overview</x-tabs.tab>
        <x-tabs.tab value="settings">Settings</x-tabs.tab>
    </x-tabs.nav>
    
    <x-tabs.panel value="overview">
        <p>Overview content...</p>
    </x-tabs.panel>
    
    <x-tabs.panel value="settings">
        <p>Settings content...</p>
    </x-tabs.panel>
</x-tabs>

{{-- Badges --}}
<x-umbra-ui::badge>Default</x-umbra-ui::badge>
<x-umbra-ui::badge variant="success">Success</x-umbra-ui::badge>
<x-umbra-ui::badge variant="error" removable="true">Removable</x-umbra-ui::badge>
<x-umbra-ui::badge variant="primary" dot="true">With Dot</x-umbra-ui::badge>
<x-umbra-ui::badge size="lg">Large Badge</x-umbra-ui::badge>

{{-- Avatars --}}
<x-umbra-ui::avatar src="/path/to/image.jpg" alt="User Name" />
<x-umbra-ui::avatar initials="JD" size="lg" />
<x-umbra-ui::avatar status="online" size="md" />
<x-umbra-ui::avatar shape="square" initials="AB" />

{{-- Interactive Components --}}
<x-accordion>
    <x-slot name="title">FAQ Item</x-slot>
    Answer content goes here...
</x-accordion>

<x-slider min="0" max="100" value="50" />
<x-date-picker value="2025-01-15" />

Toast Notifications

Simple, elegant toast notifications for Laravel applications.

Installation

For JavaScript toasts only:

<script src="{{ asset('vendor/umbra-ui/js/toast.js') }}"></script>

For server-side toasts (redirect()->with()):

<x-umbra-ui::toast-container />

For both:

<x-umbra-ui::toast-container/>
<script src="{{ asset('vendor/umbra-ui/js/toast.js') }}"></script>

Usage

Server-side (PHP):

// Using redirect()->with()
return redirect()->back()
    ->with('success', 'User created successfully!');
    // Supports: success, error, warning, info

// Using Toast Facade
use Ihxnnxs\UmbraUI\Facades\Toast;

Toast::success('User created successfully!', 'Success Title');
Toast::error('Something went wrong!');
Toast::warning('Please review your data');
Toast::info('New updates available');

Client-side (JavaScript):

<!-- Data attributes on buttons -->
<button
    data-toast-trigger
    data-toast-type="success"
    data-toast-message="Operation completed!"
    data-toast-title="Success"
>
    Show Toast
</button>

<script>
    // Direct JavaScript calls
    umbraToast.success('Success message!', 'Title');
    umbraToast.error('Error message!');
    umbraToast.warning('Warning message!');
    umbraToast.info('Info message!');
</script>

Configuration Options

Data Attributes:

• data-toast-type: success, error, warning, info, default
• data-toast-message: Toast message text
• data-toast-title: Optional title
• data-toast-position: top-left, top-right, top-center, bottom-left, bottom-right, bottom-center
• data-toast-duration: Milliseconds (default: 5000, 0 = no auto-dismiss)

JavaScript Options:

umbraToast.show('Message', 'success', 'Title', {
    position: 'top-right',
    duration: 5000,
    dismissible: true
});

Cards

{{-- Simple Card --}}
<x-card>
    <h4>Card Title</h4>
    <p>Card content goes here...</p>
</x-card>

{{-- Card with Image --}}
<x-card>
    <x-slot name="image">
        <img src="image.jpg" alt="Description" class="w-full h-48 object-cover" />
    </x-slot>
    
    <x-slot name="header">
        <h4>Card with Image</h4>
    </x-slot>
    
    <p>Content with image and header.</p>
    
    <x-slot name="footer">
        <x-button>Action</x-button>
    </x-slot>
</x-card>

Links

<x-link href="https://example.com">External Link</x-link>
<x-link href="/dashboard" class="text-blue-600">Custom Styled Link</x-link>

Tables

{{-- Basic Table --}}
<x-umbra-ui::table>
    <x-umbra-ui::table.head>
        <x-umbra-ui::table.row>
            <x-umbra-ui::table.th>Name</x-umbra-ui::table.th>
            <x-umbra-ui::table.th>Email</x-umbra-ui::table.th>
            <x-umbra-ui::table.th align="right">Actions</x-umbra-ui::table.th>
        </x-umbra-ui::table.row>
    </x-umbra-ui::table.head>
    
    <x-umbra-ui::table.body>
        <x-umbra-ui::table.row>
            <x-umbra-ui::table.td>John Doe</x-umbra-ui::table.td>
            <x-umbra-ui::table.td>john@example.com</x-umbra-ui::table.td>
            <x-umbra-ui::table.td align="right">
                <x-button class="text-xs">Edit</x-button>
            </x-umbra-ui::table.td>
        </x-umbra-ui::table.row>
        
        <x-umbra-ui::table.row selected="true">
            <x-umbra-ui::table.td>Jane Smith</x-umbra-ui::table.td>
            <x-umbra-ui::table.td>jane@example.com</x-umbra-ui::table.td>
            <x-umbra-ui::table.td align="right">
                <x-button class="text-xs">Edit</x-button>
            </x-umbra-ui::table.td>
        </x-umbra-ui::table.row>
    </x-umbra-ui::table.body>
</x-umbra-ui::table>

{{-- Empty State Table --}}
<x-umbra-ui::table>
    <x-umbra-ui::table.head>
        <x-umbra-ui::table.row>
            <x-umbra-ui::table.th>Orders</x-umbra-ui::table.th>
            <x-umbra-ui::table.th>Customer</x-umbra-ui::table.th>
            <x-umbra-ui::table.th align="right">Total</x-umbra-ui::table.th>
        </x-umbra-ui::table.row>
    </x-umbra-ui::table.head>
    
    <x-umbra-ui::table.body>
        <x-umbra-ui::table.empty colspan="3">
            <x-slot name="title">No orders found</x-slot>
            You haven't received any orders yet.
            <x-slot name="action">
                <x-button class="text-sm">Create Order</x-button>
            </x-slot>
        </x-umbra-ui::table.empty>
    </x-umbra-ui::table.body>
</x-umbra-ui::table>

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• ihxnnxs
• All Contributors
• Tabler Icons - Beautiful free SVG icons

License

The MIT License (MIT). Please see License File for more information.