Basekit Laravel UI

A modular Laravel 12 UI component library with reusable Blade components, Tailwind 4 CSS theming, and component-aware CSS builds for optimal performance.

Features

• 🎨 Tailwind 4 CSS-based theming - Runtime customization via CSS variables
• 🔧 Highly configurable - Enable/disable components, customize variants and sizes
• 🌲 Component-aware CSS build - Include CSS only for enabled components
• 🎯 Type-safe components - PHP classes with IDE autocomplete
• ✨ Heroicons integration - Beautiful icons out of the box
• 📦 Publishable views - Customize component templates directly

Installation

Basic Setup

Install via Composer:

composer require basekit-laravel/basekit-laravel-ui

Include the CSS in your main CSS file:

@import "./vendor/basekit-laravel/v1/basekit-ui.css";

Include Alpine.js

Several Basekit components (Accordion, Dropdown Menu, Input password toggle, Modal, Multi-Select, Tabs, Toast, Tooltip, and Table) require Alpine.js. Add it to your layout:

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

Or with Livewire, use @livewireScripts which includes Alpine.js automatically:

@livewireScripts

See the installation guide for more details.

Advanced Setup

Publish the configuration file:

php artisan vendor:publish --tag=basekit-laravel-ui-config

Publish the CSS theme:

php artisan vendor:publish --tag=basekit-laravel-ui-css-v1

Build optimized CSS based on your configuration:

php artisan basekit:ui:build

For development, use watch mode:

php artisan basekit:ui:build --watch

Quick Start

<x-basekit-ui::button variant="primary" icon="check">
    Save Changes
</x-basekit-ui::button>

<x-basekit-ui::input
    label="Email"
    placeholder="Enter your email"
    icon="envelope"
/>

<x-basekit-ui::card>
    <x-slot:header>
        <h3>Card Title</h3>
    </x-slot>

    Card content goes here...

    <x-slot:footer>
        <x-basekit-ui::button>Action</x-basekit-ui::button>
    </x-slot>
</x-basekit-ui::card>

Styling Conventions

• Component CSS uses BEM with the bk- prefix (blocks, elements, and modifiers).
• Tailwind utilities are for component usage in Blade markup (layout, spacing, overrides).
• When combining classes, Tailwind Merge handles conflicts for the class attribute.

Configuration

Edit config/basekit-laravel-ui.php to customize components:

return [
    'components' => [
        'button' => [
            'enabled' => true,
            'variants' => ['primary', 'secondary', 'danger'],
            'sizes' => ['sm', 'md', 'lg'],
            'default_variant' => 'primary',
            'default_size' => 'md',
        ],
        // ... more components
    ],

    'icons' => [
        'style' => 'outline', // outline, solid, mini
    ],

    'build' => [
        'debounce_ms' => 500,
    ],
];

After changing configuration, rebuild CSS:

php artisan basekit:ui:build

For development, use watch mode:

php artisan basekit:ui:build --watch

Customization

CSS Variables

Override theme variables in your CSS:

:root {
  --color-primary-600: #your-brand-color;
  --button-radius: 0.5rem;
  --card-padding: 2rem;
}

Publishing Views

Publish component views for full customization:

php artisan vendor:publish --tag=basekit-views

Published views are copied to resources/views/vendor/basekit/ and automatically override package components.

Available Components

The package includes 33 production-ready components organized into 6 categories:

Form Components (8)

• Button
• Input
• Textarea
• Checkbox
• Radio
• Select
• Multi-Select
• Toggle

Feedback Components (7)

• Alert
• Toast
• Tooltip
• Progress
• Spinner
• Skeleton
• Empty State

Navigation Components (5)

• Breadcrumb
• Pagination
• Tabs
• Dropdown Menu
• Link

Layout Components (4)

• Stack
• Grid
• Container
• Divider

Display Components (7)

• Table
• List
• Description List
• Stat
• Card
• Badge
• Avatar

Dialog & Overlay (2)

• Modal
• Accordion

Documentation

Full documentation available at: https://basekit-laravel.github.io/basekit-laravel-ui

See also:

• IMPLEMENTATION.md — Architecture and development guide
• STRUCTURE.md — Component organization and relationships

CI Quality Checks

The CI workflow validates production readiness on pushes and pull requests by running:

• Feature tests: php vendor/bin/pest --no-coverage
• CSS build: ./vendor/bin/testbench basekit:ui:build
• Styleguide generation: ./vendor/bin/testbench basekit:ui:styleguide
• CSS/docs token sync guard: bash tools/verify-doc-token-sync.sh

You can run these locally before opening a pull request.

Performance

Component-based builds can significantly reduce bundle size:

• Full bundle (all components): ~200KB
• Minimal config (3 components): ~55KB
• Reduction: 73%

Migration

See CHANGELOG.md for version changes and migration guides.

License

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