README

Basekit Laravel UI

A modular Laravel UI component library built with Blade components, Tailwind 4 CSS, and Alpine.js for rich, interactive interfaces.
Create rich, production‑ready UIs faster with 33 pre‑built components, configurable theming, and a built‑in style guide.

Explore all components in the style guide and read the full docs at basekit‑laravel.github.io/basekit‑laravel‑ui.

🌟 Features

• 🎨 Tailwind 4 CSS‑based theming – Runtime customization via CSS variables.
• ✨ Heroicons integration – Beautiful icons out of the box.
• 🔧 Component toggle & defaults – Enable/disable components and set default variants and sizes.
• 🌲 Component‑aware CSS build – Include CSS only for enabled components.
• 🎯 Type‑safe components – PHP classes with IDE autocomplete.
• 📦 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

🧩 Available Components

The package includes 33 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

🧾 Example Form

<x-basekit-ui::container>
    <x-basekit-ui::card>
        <x-slot:header>
            <h2 class="text-xl font-bold">Create Account</h2>
        </x-slot>

        <form method="POST" action="/register">
            @csrf

            <x-basekit-ui::stack spacing="lg">
                <x-basekit-ui::input
                    name="name"
                    label="Name"
                    icon="user"
                    :error="$errors->first('name')"
                />

                <x-basekit-ui::input
                    name="email"
                    type="email"
                    label="Email"
                    icon="envelope"
                    :error="$errors->first('email')"
                />

                <x-basekit-ui::input
                    name="password"
                    type="password"
                    label="Password"
                    hint="Must be at least 8 characters"
                    icon="lock-closed"
                    :error="$errors->first('password')"
                />

                <x-basekit-ui::checkbox
                    name="terms"
                    label="I agree to the terms and conditions"
                />
            </x-basekit-ui::stack>

            <x-slot:footer>
                <div class="flex justify-between items-center">
                    <x-basekit-ui::link href="/login">
                        Already have an account?
                    </x-basekit-ui::link>

                    <x-basekit-ui::button
                        type="submit"
                        variant="primary"
                        icon="arrow-right"
                    >
                        Create Account
                    </x-basekit-ui::button>
                </div>
            </x-slot>
        </form>
    </x-basekit-ui::card>
</x-basekit-ui::container>

Browse all available components in the style guide and read the full docs at basekit-laravel.github.io/basekit-laravel-ui.

⚙️ 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;
}

See the full list of available variables in the Complete CSS variable reference in the documentation.

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.

📐 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.

🧪 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.

📚 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

📄 License

The MIT License (MIT). Please see the LICENSE file for more information.