Getting Started

Minimal Steps

Installation

composer require pushery/wirekit

Add to your layout:

<head>
    @wirekitStyles
    @vite(['resources/css/app.css', 'resources/js/app.js'])
</head>
<body>
    {{ $slot }}
    @wirekitScripts
</body>

Include Blade source path in app.css:

@source '../../vendor/pushery/wirekit/resources/views/**/*.blade.php';

First Component Use a basic form component in a Livewire blade:

<x-wirekit::input
    label="Email"
    type="email"
    name="email"
    wire:model="email"
/>

Verify Setup Run the CLI doctor to check for common issues:
```
php artisan wirekit:doctor
```

First Use Case

Replace a vanilla Livewire form with WireKit’s pre-styled components:

<x-wirekit::form wire:submit="save">
    <x-wirekit::input label="Username" wire:model="username" />
    <x-wirekit::button type="submit">Save</x-wirekit::button>
</x-wirekit::form>

Key: Leverage wire:model for Livewire integration while gaining Tailwind-styled UI.

Implementation Patterns

Core Workflows

Component Composition Use slots for custom content (e.g., dropdown triggers):

<x-wirekit::dropdown>
    <x-slot:trigger>
        <x-wirekit::button>Menu</x-wirekit::button>
    </x-slot:trigger>
    <x-wirekit::dropdown.item>Item 1</x-wirekit::dropdown.item>
</x-wirekit::dropdown>

Livewire Integration Bind stateful controls with wire:model:
```
<x-wirekit::slider
    label="Volume"
    wire:model="volume"
    :min="0"
    :max="100"
/>
```
Tip: Use .debounce or .lazy for sliders to avoid excessive Livewire updates.

Theming Override CSS variables in app.css:

@layer base {
    :root {
        --color-wk-accent: var(--color-blue-600);
    }
}

Dark Mode WireKit is dark-mode aware by default. Use dark: variants in Tailwind:
```
<x-wirekit::button class="dark:bg-gray-800">Toggle</x-wirekit::button>
```

Integration Tips

Icons: Use semantic aliases (e.g., icon="copy"). Configure presets in config/wirekit.php:
```
'icons' => [
    'presets' => ['heroicons', 'lucide'],
],
```

Charts: Switch libraries via config:

'charts' => [
    'library' => 'apexcharts', // or 'chartjs'
],

Forms: Use <x-wirekit::form> with wire:submit for validation-aware submissions.

Advanced Patterns

Event Listeners Listen to component events (e.g., tab changes):

<x-wirekit::tabs x-on:wirekit:tab-changed="$wire.onTabChanged($event.detail.tab)">
    <!-- tabs -->
</x-wirekit::tabs>

Livewire Method:

public function onTabChanged($tab) {
    $this->activeTab = $tab;
}

Custom Components Extend WireKit’s structure:

<x-wirekit::card>
    <x-slot:header>
        <h3>Custom Card</h3>
    </x-slot:header>
    <p>Content here.</p>
</x-wirekit::card>

CLI Introspection Inspect components dynamically:
```
php artisan wirekit:show dropdown --as=json
```

Gotchas and Tips

Pitfalls

Livewire Binding
- Issue: Stateful controls (e.g., <x-wirekit::slider>) may trigger excessive Livewire updates if not debounced.
- Fix: Use wire:model.lazy or wire:model.debounce.500ms.
Icon Aliases
- Issue: Custom icon aliases may fail if not configured in config/wirekit.php.
- Fix: Verify presets and use the icon documentation.
Editor Extensions
- Issue: <x-wirekit::editor>’s extensions prop defaults to [] (not ['StarterKit']).
- Fix: Ensure your window.tiptapEditor factory handles extensions independently.
Dark Mode Contrast
- Issue: Decorative borders may trigger false WCAG failures.
- Fix: Use wirekit:doctor:a11y --theme-contrast to audit and exempt decorative borders.
Multi-Select Pre-Selection
- Issue: :value prop on <x-wirekit::multi-select> may not work if passed incorrectly.
- Fix: Use an array of option keys (e.g., :value="['php', 'js']").

Debugging

Unknown Props: Enable WireKit’s debug mode to catch invalid props in tests:
```
// In a test:
$this->assertWireKitPropWarning('invalid-prop');
```
CLI Doctor: Run php artisan wirekit:doctor to diagnose setup issues.
Manifests: Use wirekit:export-json to generate machine-readable component schemas.

Extension Points

Custom Themes Override CSS variables globally or per-component:

.custom-theme .wk-button {
    --color-wk-accent: #ff0000;
}

Slot Overrides Replace default slots (e.g., <x-slot:trigger> in dropdowns) for full control.
Chart Libraries Mix chartjs and apexcharts by overriding per-instance:
```
<x-wirekit::chart library="apexcharts" ...>
```
Accessibility Use wirekit:doctor:a11y to audit contrast and keyboard navigation.

Pro Tips

Component Discovery: Browse the live docs for interactive examples.

Performance: Lazy-load heavy components (e.g., charts) with Alpine.js:

<x-wirekit::chart x-data="{ loaded: false }" x-on:load="loaded = true" ...>
    <div x-show="loaded">...</div>
</x-wirekit::chart>

Livewire + Alpine: Combine wire:model with Alpine for reactive UIs:

<x-wirekit::input
    wire:model="search"
    x-model="localSearch"
    x-on:input="$wire.set('search', $event.target.value)"
/>

Wirekit Laravel Package