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 ✅

Component	Status	Description
Button	✅ Ready	Primary, secondary, and variant styles
Input	✅ Ready	Text, email, password, number inputs
Link	✅ Ready	Styled anchor elements
Textarea	✅ Ready	Multi-line text input
Select	✅ Ready	Dropdown selection
Checkbox	✅ Ready	Boolean selection
Radio	✅ Ready	Single choice selection
Label	✅ Ready	Form field labels
Field	✅ Ready	Form field wrapper with validation
Switch	✅ Ready	Toggle switch
Slider	✅ Ready	Range input
Date Picker	✅ Ready	Date selection

Navigation & Layout ✅

Component	Status	Description
Alert	✅ Ready	Success, error, warning, info
Badge	✅ Ready	Status indicators and labels
Avatar	✅ Ready	User profile pictures and initials
Tabs	✅ Ready	Tabbed navigation interface
Accordion	✅ Ready	Collapsible content sections
Modal	✅ Ready	Dialog/popup overlay
Card	✅ Ready	Universal card with image support
Dropdown	✅ Ready	Context menus with nested submenus
Popover	✅ Ready	Contextual overlay with click/hover
Tooltip	✅ Ready	Accessible hover/focus tooltip
Spinner	✅ Ready	Loading animations and states
Divider	✅ Ready	Content separators
Progress	✅ Ready	Progress indicators
Breadcrumb	✅ Ready	Navigation breadcrumbs

Data Display ✅

Component	Status	Description
Table	✅ Ready	Data tables with sorting and selection support

Notifications ✅

Component	Status	Description
Toast	✅ Ready	Elegant notification system

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.

ihxnnxs / umbra-ui

Maintainers

Details

README

UmbraUI

✨ Key Features

Essential Components

Core Form Components ✅

Navigation & Layout ✅

Data Display ✅

Notifications ✅

Icons

📋 Requirements

📦 Installation

Add Alpine.js (Required for Interactive Components)

Publishing Assets (Optional)

🚀 Quick Start

Theme Customization

Installing Additional Components

Usage

Basic Components

Advanced Components

Toast Notifications

Installation

Usage

Configuration Options

Cards

Links

Tables

Testing

Changelog

Contributing

Security Vulnerabilities

Credits

License