README

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)

Feedback Components (7)

Navigation Components (5)

Layout Components (4)

Display Components (7)

Dialog & Overlay (2)

Documentation

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

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.

basekit-laravel / basekit-laravel-ui

Maintainers

Package info

Statistics

Security