Klementine UI

Laravel Blade component library built on Web Awesome and Alpine.js. Provides form controls, overlays, file uploads, and a shared design token layer for Laravel applications.

Requirements

PHP 8.3+
Laravel 13+
Node.js 20+ with npm
Vite (via laravel-vite-plugin)

Installation

1. Composer

Add the package to your Laravel project. For local development, use a path repository:

composer require codeartlv/klementine-ui

The service provider is auto-discovered via Laravel package discovery.

2. Publish configuration (optional)

php artisan vendor:publish --tag=klementine-config

This creates config/klementine.php:

return [
    'component_prefix' => 'ui', // Blade tags become <x-ui-button>, <x-ui-input>, etc.
];

If the config file is not published, the prefix defaults to ui.

3. Frontend dependencies

After composer require, install the package's npm dependencies:

php artisan klementine-ui:install

This runs npm install in the package directory (works for path repos and vendor/codeartlv/klementine-ui). Node.js must be available on the machine.

4. Automate with Composer (optional)

The install command does not run automatically when the package is required. To run it after every composer install or composer update, add hooks to your application's root composer.json:

{
	"scripts": {
		"post-install-cmd": ["@php artisan klementine-ui:install --ansi"],
		"post-update-cmd": ["@php artisan klementine-ui:install --ansi"]
	}
}

If you already have post-install-cmd or post-update-cmd entries, append the artisan line to those arrays instead of replacing them:

{
	"scripts": {
		"post-update-cmd": [
			"@php artisan vendor:publish --tag=laravel-assets --ansi --force",
			"@php artisan klementine-ui:install --ansi"
		]
	}
}

You can also call it from a custom setup script:

{
	"scripts": {
		"setup": [
			"composer install",
			"@php artisan klementine-ui:install --ansi",
			"npm install --ignore-scripts",
			"npm run build"
		]
	}
}

Hook	Runs when
`post-install-cmd`	`composer install`
`post-update-cmd`	`composer update`, `composer require`, `composer remove`

5. Vite alias

Add a path alias in vite.config.mjs so imports resolve to the package resources:

import path from 'path';

export default defineConfig({
	resolve: {
		alias: {
			'@klementine-ui': path.resolve('vendor/codeartlv/klementine-ui/resources'),
		},
	},
});

6. Application entry point

Create or update resources/js/app.js:

import KlementineUI from '@klementine-ui/js';

KlementineUI.configureAlpine((Alpine) => {
	// Register custom Alpine components (optional)
}).configureWebAwesome((registerIconLibrary) => {
	// Configure Web Awesome settings (optional)
});

KlementineUI.start();

Include Vite assets in your layout:

@vite(['resources/js/app.js', 'resources/css/app.css'])

Add a CSRF meta tag for AJAX forms and overlays:

<meta name="csrf-token" content="{{ csrf_token() }}">

7. Styles

Import Klementine styles in your app CSS (the preview app uses the parent resources/css/app.css which should import or mirror the package layer structure). The package stylesheet entry is:

@import '@klementine-ui/css/app.css';

It layers Web Awesome, design tokens (variables.css), form styles, and per-component CSS.

8. Web Awesome assets

Web Awesome static assets must be available at /build/webawesome in production. Configure the base path in KlementineUI.setupWebAwesome() (handled automatically when using the package entry point).

Preview

When running locally, open the component preview at:

http://localhost/klementine-ui

(Requires the package dev routes — registered on the localhost domain.)

Each component demo lives in resources/views/preview/components/.

Architecture

Layer	Location	Purpose
Blade components	`src/View/Components/`	Server-rendered UI tags
Blade views	`resources/views/`	Component markup
Alpine components	`resources/js/alpine-components/`	Auto-registered as `Alpine.data()`
UI factories	`resources/js/ui-components/`	Programmatic DOM builders
Overlay loader	`resources/js/lib/overlay-loader.js`	Shared dialog/drawer AJAX logic

Alpine components are registered automatically from filenames:

File	Alpine name	Usage
`dialog.js`	`dialog`	`x-data="dialog(url, caption, id)"`
`drawer.js`	`drawer`	`x-data="drawer(url, caption, id)"`
`form.js`	`form`	`x-data="form"` on `<x-ui-form>`
`fileUploader.js`	`fileUploader`	Used by `<x-ui-uploader>`
`passwordField.js`	`passwordField`	Used by `<x-ui-password>`
`datepicker.js`	`datepicker`	Used by `<x-ui-datepicker>`

Components

All examples use the default ui prefix: <x-ui-{name}>. Replace ui if you changed component_prefix in config.

Avatar

<x-ui-avatar image="https://example.com/photo.jpg" loading="lazy" />
<x-ui-avatar initials="WA" />

Additional Web Awesome attributes (shape, size, etc.) can be passed through {{ $attributes }}.

Badge

<x-ui-badge label="New" variant="primary" />
<x-ui-badge label="Draft" variant="neutral" appearance="outlined" pill />
<x-ui-badge label="3" variant="danger" attention="pulse" pill />

Prop / attribute	Description
`label`	Badge text
`variant`	`primary`, `success`, `neutral`, `warning`, `danger`
`appearance`	`filled`, `outlined`, `filled-outlined`
`pill`	Rounded pill shape
`attention`	e.g. `pulse` for animation

Button

<x-ui-button label="Save" variant="brand" appearance="filled" />
<x-ui-button type="submit" label="Submit" variant="brand" span />

Prop	Description
`label`	Button text
`type`	`button`, `submit`, `reset`
`span`	Full-width block button

Pass Web Awesome attributes (variant, appearance, size, disabled, loading) as HTML attributes.

Callout

<x-ui-callout
    title="Heads up"
    message="Something needs your attention."
    variant="warning"
/>

Prop	Description
`title`	Optional heading
`message`	Body text (supports HTML)
`variant`	`brand`, `success`, `warning`, `neutral`, `danger`
`size`	`xs`, `s`, `m`, `l`, `xl`

Checkbox

<x-ui-checkbox name="agree" label="I agree" value="1" />
<x-ui-checkbox name="agree" label="With hint" hint="Required to continue" />
<x-ui-checkbox name="agree" label="Disabled" disabled />

Radio

<x-ui-radio name="plan" label="Basic" value="basic" />
<x-ui-radio name="plan" label="Pro" value="pro" />

Input

<x-ui-input name="name" label="Name" hint="Your full name" />
<x-ui-input name="email" label="Email" type="email" required />

Prop	Description
`name`	Field name
`label`	Label text
`type`	Input type (default `text`)
`value`	Initial value
`hint`	Helper text below the field
`required`	Shows required indicator on label

Textarea

<x-ui-textarea name="bio" label="Bio" hint="Tell us about yourself" />

Select

@php
use Codeart\Klementine\View\Components\Select\Option;
use Codeart\Klementine\View\Components\Select\Group;

$options = [
    new Option('1', 'Option 1'),
    new Option('2', 'Option 2', selected: true),
];
@endphp

<x-ui-select name="country" label="Country" :options="$options" placeholder="Choose…" />
<x-ui-select name="tags" label="Tags" :options="$options" multiple />

Options can also be Group instances for grouped <wa-option> lists.

Datepicker

<x-ui-datepicker name="date" label="Date" :value="$date" display-format="d.m.Y" />

Uses Vanilla Calendar Pro with an Alpine datepicker component.

Password

<x-ui-password
    name="password"
    label="Password"
    policy="min:8,max:64,lowercase,uppercase,number,special"
/>

Policy is a comma-separated rule string consumed by the passwordField Alpine component (live strength meter and rule checklist).

Form

Wrap fields in a form that submits via AJAX and displays validation errors inline.

<x-ui-form method="post" action="{{ route('profile.update') }}">
    <x-ui-form-group>
        <x-ui-input name="name" label="Name" />
        <x-ui-input name="email" label="Email" type="email" />
        <x-ui-button type="submit" label="Save" variant="brand" span />
    </x-ui-form-group>
</x-ui-form>

Server response — return JSON using FormResponse:

use Codeart\Klementine\View\Components\Forms\FormError;
use Codeart\Klementine\View\Components\Forms\FormResponse;
use Codeart\Klementine\View\Components\Forms\FormSuccess;

$response = new FormResponse();
$response->addError(new FormError('Name is required', 'name'));
return response()->json($response);

// Or on success:
$response = new FormResponse();
$response->setSuccess(new FormSuccess('Saved successfully'));
$response->addSuccessAction('redirect', '/dashboard');
return response()->json($response);

Dialog

Declarative (Blade):

<x-ui-dialog label="Confirm" id="confirm-dialog">
    <p>Are you sure?</p>
    <div slot="footer">
        <x-ui-button label="Close" variant="brand" data-dialog="close" />
    </div>
</x-ui-dialog>

<button data-dialog="open confirm-dialog">Open</button>

Alpine (load content on click):

<a href="#" x-data="dialog('{{ route('items.edit', $item) }}', 'Edit item')">
    Edit
</a>

JavaScript:

import Dialog from '@klementine-ui/js/ui-components/dialog.js';

const dialog = new Dialog({ id: 'edit-item', caption: 'Edit item' });

// Load HTML from URL
await dialog.open('/items/1/edit');

// Or wrap an existing element
await dialog.open(document.getElementById('my-panel'));

// Options
await dialog.open('/items/1/edit', { autoclose: true, animations: false });

dialog.on('close', () => {
	/* … */
});
dialog.close();

Constructor param	Description
`id`	CSS class suffix (`dialog--{id}`)
`caption`	Dialog title (maps to `label` on `<wa-dialog>`)

`open()` option	Description
`autoclose`	Enables `light-dismiss` on overlay click
`animations`	Set `false` to disable show/hide animation

Drawer

Same API as dialog, backed by <wa-drawer>:

<a href="#" x-data="drawer('{{ route('menu') }}', 'Menu')">Open menu</a>

import Drawer from '@klementine-ui/js/ui-components/drawer.js';

const drawer = new Drawer({ id: 'menu', caption: 'Menu' });
await drawer.open('/navigation', { placement: 'start', autoclose: true });

Close buttons inside a drawer use data-drawer="close".

Uploader

<x-ui-uploader
    name="files"
    data-uploadroute="{{ route('upload') }}"
    data-deleteroute="{{ route('upload.delete') }}"
    data-limit="5"
/>

Attribute	Description
`data-uploadroute`	POST endpoint for file chunks
`data-deleteroute`	DELETE endpoint for removing files
`data-croproute`	Optional crop endpoint
`data-limit`	Max number of files (default `1`)
`data-submitbtn`	Selector for submit button to disable during upload

Translations for placeholders and error messages come from lang/{locale}/components.php under the klementine-ui namespace.

Icon

<x-ui-icon name="upload" />
<x-ui-icon name="circle-xmark" size="l" />

Form group

Layout wrapper for stacking form fields:

<x-ui-form-group>
    <x-ui-input name="first" label="First name" />
    <x-ui-input name="last" label="Last name" />
</x-ui-form-group>

JavaScript API

KlementineUI

import KlementineUI from '@klementine-ui/js';

KlementineUI.configureAlpine((Alpine) => {
	Alpine.data('myComponent', () => ({
		/* … */
	}));
})
	.configureWebAwesome((registerIconLibrary) => {
		// Register custom icon libraries
	})
	.start();

start() loads all Alpine components from alpine-components/ and calls Alpine.start().

UI component factories

For dynamic DOM (used internally by forms and overlays):

import button from '@klementine-ui/js/ui-components/button.js';
import callout from '@klementine-ui/js/ui-components/callout.js';
import spinner from '@klementine-ui/js/ui-components/spinner.js';

document.body.appendChild(callout({ variant: 'danger', message: 'Error' }));

Translations

Publish or extend translation files at lang/{locale}/components.php:

return [
    'uploader' => [
        'upload_placeholder' => 'Upload files',
        'upload_max_filesize' => 'File exceeds the maximum size (:max MB)',
    ],
    'password_field' => [
        'password_hint' => [
            'lowercase' => 'Lowercase letter',
            // …
        ],
    ],
];

Loaded under the klementine-ui::components.* namespace.

Development

# In the package directory
npm run dev

# In the Laravel app
npm run dev
php artisan serve

Visit http://localhost/klementine-ui for the live component preview.

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
config		config
lang/lv		lang/lv
resources		resources
src		src
.gitignore		.gitignore
README.md		README.md
composer.json		composer.json
composer.lock		composer.lock
llms.txt		llms.txt
package-lock.json		package-lock.json
package.json		package.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Klementine UI

Requirements

Installation

1. Composer

2. Publish configuration (optional)

3. Frontend dependencies

4. Automate with Composer (optional)

5. Vite alias

6. Application entry point

7. Styles

8. Web Awesome assets

Preview

Architecture

Components

Avatar

Badge

Button

Callout

Checkbox

Radio

Input

Textarea

Select

Datepicker

Password

Form

Dialog

Drawer

Uploader

Icon

Form group

JavaScript API

KlementineUI

UI component factories

Translations

Development

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages