README

A Laravel Livewire UI component library with Heroicons integration, dark mode support, and Alpine.js-powered interactivity.

Requirements

PHP 8.1+
Laravel 10+
Livewire 4+
Alpine.js 3+

Installation

Install the package via Composer:

composer require phara/ui-kit

The service provider is auto-discovered by Laravel — no manual registration needed.

Layout Setup

Add @uiStyles in the <head> and @uiScripts before </body> in your layout file:

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

    @livewireScripts
    @uiScripts
    @stack('scripts')
</body>

@stack('scripts') is required — components like Chart, Calendar, and Toast push scripts to this stack.

Alpine.js Setup

If Alpine.js is not already installed:

npm install alpinejs

Then in your resources/js/app.js:

import Alpine from 'alpinejs';

window.Alpine = Alpine;

Alpine.start();

Usage

All components are available under the ui:: namespace:

<x-ui::button>Click me</x-ui::button>
<x-ui::icon name="heart" />

Components

Button

<x-ui::button variant="primary">Click me</x-ui::button>

<!-- With icon -->
<x-ui::button variant="primary" icon="check">Save</x-ui::button>

<!-- Icon on the right -->
<x-ui::button variant="primary" icon="arrow-right" iconPosition="right">Next</x-ui::button>

<!-- As a link -->
<x-ui::button href="/dashboard" variant="secondary" icon="home">Dashboard</x-ui::button>

Prop	Values	Default
`variant`	`primary`, `secondary`, `danger`, `outline`, `ghost`	`primary`
`size`	`sm`, `md`, `lg`	`md`
`icon`	Any Heroicon name	—
`iconPosition`	`left`, `right`	`left`
`href`	URL string	—

Icon

All 324 Heroicons are included out of the box.

<x-ui::icon name="user" />
<x-ui::icon name="heart" variant="solid" size="lg" />
<x-ui::icon name="cog" variant="outline" size="sm" class="text-blue-500" />

Prop	Values	Default
`name`	Any Heroicon name	required
`variant`	`outline`, `solid`	`outline`
`size`	`xs`, `sm`, `md`, `lg`, `xl`	`md`

Input

<x-ui::input name="email" type="email" label="Email Address" placeholder="you@example.com" />

<!-- With icon -->
<x-ui::input name="search" icon="magnifying-glass" placeholder="Search..." />

<!-- Password with show/hide toggle -->
<x-ui::input name="password" type="password" placeholder="Password" />

<!-- Readonly with copy button -->
<x-ui::input name="token" readonly value="your-api-token-here" />

Prop	Values	Default
`name`	string	required
`label`	string	—
`type`	`text`, `email`, `password`, `search`, etc.	`text`
`size`	`sm`, `md`, `lg`	`md`
`variant`	`default`, `filled`	`default`
`icon`	Any Heroicon name	—

Smart behaviors:

type="search" — shows a clear (×) button when the field has a value
type="password" — shows an eye icon to toggle visibility
readonly — shows a copy-to-clipboard button automatically

Copy to Clipboard

<!-- Button style -->
<x-ui::copy-to-clipboard text="composer require phara/ui-kit">
    Copy Install Command
</x-ui::copy-to-clipboard>

<!-- Icon-only style -->
<x-ui::copy-to-clipboard text="your-api-key" style="icon" />

<!-- Custom success message -->
<x-ui::copy-to-clipboard text="secret-key" successMessage="Key copied!">
    Copy Key
</x-ui::copy-to-clipboard>

Prop	Values	Default
`text`	string	—
`style`	`button`, `icon`	`button`
`variant`	`default`, `primary`, `ghost`, `outline`	`default`
`size`	`sm`, `md`, `lg`	`md`
`successMessage`	string	`Copied!`
`icon`	Heroicon name	`clipboard-document`
`successIcon`	Heroicon name	`check`

Theme Toggle

<!-- Button style -->
<x-ui::theme-toggle />

<!-- Toggle switch style -->
<x-ui::theme-toggle style="toggle" size="lg" />

Prop	Values	Default
`style`	`button`, `toggle`	`button`
`size`	`sm`, `md`, `lg`	`md`

Automatically detects system preference on first load and persists the user's choice in localStorage.

Dark Mode

All components support dark mode out of the box. No extra configuration needed.

Icons Reference

Browse all available icons at heroicons.com. Use the icon name directly in any icon prop:

<x-ui::icon name="magnifying-glass" />
<x-ui::icon name="arrow-right" variant="solid" />

License

MIT

phara/ui-kit

包简介

README 文档