VKM APPS | X-Form

✨ Supercharge your Laravel form building!

Create beautiful, fully interactive forms in a single line of Blade code. No more repeating boilerplate layouts, validation classes, error handlers, and input styles! 🚀💻

X-Form is a highly polished collection of Blade components for Laravel 11, 12, and 13+, built on top of Livewire 3, Tailwind CSS 4, and AlpineJS 3. It makes form creation lightning-fast and fully interactive while ensuring complete customization via published configurations.

To enjoy full compatibility, please install the VKM JS plugins bundle: 👉 https://github.com/vkm-apps/vkm-js

Requirements

• PHP: ^8.1
• Laravel / Support: ^11.0 | ^12.0 | ^13.0
• Livewire: ^3.0
• AlpineJS: ^3.0
• Tailwind CSS: ^4.0

Installation & Setup

Install the package via Composer:

composer require vkm-apps/x-form

Install and publish the configuration files using the setup command:

php artisan x-form:install

[!NOTE] The install command automatically publishes the package configuration file to config/x-form.php. You can customize styles, Tailwind classes, default icons, and other behavioral settings.

Available Components

Here is a summary of the available Blade components and their key features:

Global Features & Shared Attributes

All components inheriting from the core FormElement support a set of rich, interactive features that make writing beautiful, accessible interfaces straightforward:

1. Tooltips & Help Popovers

Add quick informational tips next to your labels automatically.

• tooltip="Your message": Shows a small info icon next to the label that displays a tooltip on hover.
• help="Your rich HTML message": Shows an info icon that opens an AlpineJS popover dialog on click.

<x-form.input model="title" label="Title" tooltip="This is a short tooltip." />
<x-form.input model="slug" label="Slug" help="<strong>URL friendly</strong> slug. Only letters, numbers, and dashes are allowed." />

2. Required Markings

• required: Adds a red asterisk (*) to the label automatically.

<x-form.input model="name" label="Name" required />

3. Prepend & Append Slots

Enables nesting icons, buttons, text badges, or custom HTML inside the input layout.

• <x-slot:prepend>: Inserts content before the input field.
• <x-slot:append>: Inserts content after the input field.

<x-form.input model="price" label="Price" type="number">
    <x-slot:prepend><span class="px-2 text-gray-500">$</span></x-slot:prepend>
    <x-slot:append><span class="px-2 text-gray-500">USD</span></x-slot:append>
</x-form.input>

4. Livewire Model Modifiers

Binds model updates utilizing Livewire modifiers out of the box:

• live: Updates the model on every keypress (wire:model.live).
• blur: Updates the model when input focus is lost (wire:model.live.blur).
• change: Updates the model when input selection changes (wire:model.live.change).

<x-form.input model="search" label="Search" live />

Input

A fully customizable input field with automated label generation, validation highlights, accessibility attributes, and error message outputs.

<x-form.input model="title" label="Title" />

Component Properties

{{-- Large, instantly validating number input --}}
<x-form.input type="number" model="age" label="Age" group="lg" validate="blur" required />

Textarea

Textareas support character counts, maximum limits, auto-height resizing, and error bindings.

<x-form.textarea model="description" label="Description" placeholder="Enter details..." />

Component Properties

{{-- Textarea with a 250-character limit counter --}}
<x-form.textarea model="bio" label="Biography" limit="250" rows="4" required />

Password

A secure password input that automatically renders a show/hide toggle button (eye icon) using AlpineJS under the hood.

<x-form.password model="password" label="New Password" required />

Component Properties

Select and Dropdown

Renders an interactive dropdown with custom searching, styled scrollbars, and dynamic state bindings. Alternatively, it can fall back to a native browser select element.

<x-form.select :list="$this->countryList" model="country" label="Country of Origin" />

Component Properties

Options Array Format

Ensure arrays use string keys to preserve ordering on the frontend:

#[Computed]
public function countryList(): array
{
    return [
        'Greece' => 'gr',
        'Italy' => 'it',
        'Spain' => 'es',
    ];
}

Advanced Select Usage

{{-- Custom searchable dropdown with inline input --}}
<x-form.select
    :list="$this->countryList"
    model="country"
    label="Country"
    searchable
    inline
    title="Choose a destination..."
/>

{{-- Native browser select fallback --}}
<x-form.select
    :list="$this->countryList"
    model="country"
    label="Country"
    :dropdown="false"
/>

Checkboxes and Radio Buttons

Tailwind-styled choice groups supporting horizontal/vertical alignments, descriptions, tooltips, and interactive group toggles.

Single Checkbox (Boolean)

If you omit the :list attribute, the component renders a single checkbox representing a boolean value (e.g., binds to a boolean property true/false). The label is displayed inline next to the checkbox.

<x-form.checkbox model="remember_me" label="Remember Me" required />

Flat Checkbox Group

If you pass the :list attribute, the component renders a list of checkboxes matching the option keys and values. The label is displayed as a header above the list.

<x-form.checkbox :list="$this->optionsList" model="interests" label="Interests" />

Radio Group

<x-form.radio :list="$this->optionsList" model="gender" label="Gender" />

Component Properties (Checkbox & Radio)

{{-- Horizontal row alignment for Radios --}}
<x-form.radio :list="$this->optionsList" model="gender" horizontal />

Grouped Checkboxes (With Header Checkboxes & Tooltips)

Grouped checkboxes are designed for complex nested layouts (e.g., system permissions categorized by module) and support dynamic tooltips and automatic header toggles.

You can use either:

<x-form.checkbox-group :list="$countries" model="selectedCountries" label="Destination Countries" />

or the group attribute alias:

<x-form.checkbox :list="$countries" model="selectedCountries" label="Destination Countries" group />

Header Checkbox Select-All: Each category header features a functional checkbox. Checking/unchecking the header checkbox toggles all items in that category client-side via AlpineJS. In addition, checking all individual items in a category automatically checks the header checkbox.

Example Array Structure:

$countries = [
    'Europe' => [
        ['id' => 'gr', 'title' => 'Greece', 'description' => 'Greece is located in southeastern Europe.'],
        ['id' => 'it', 'title' => 'Italy', 'description' => 'Italy is a peninsula in the Mediterranean Sea.'],
    ],
    'Asia' => [
        ['id' => 'jp', 'title' => 'Japan', 'description' => 'Japan is an island country in East Asia.'],
    ],
];

Custom Livewire Toggle Function (Optional): If you want to run backend PHP code when a group header is clicked, pass the toggle attribute with your Livewire method name:

public function toggleGroup($groupName)
{
    // $groupName is passed as 'Europe' or 'Asia'
    // Custom select-all or deselect-all logic here...
}

<x-form.checkbox
    :list="$countries"
    model="selectedCountries"
    label="Destination Countries"
    group
    toggle="toggleGroup"
    tooltip-key="description"
/>

Date Picker

A powerful, native-feeling calendar date input wrapper that uses the AlpineJS date picker extension. It supports ranges, locales, and handles both Livewire property binding and normal HTML form submissions.

Component Properties

Single Date Picker

<x-form.date model="appointment_date" label="Appointment Date" />

Date Range Picker

When range is enabled, the component displays two side-by-side inputs for selecting start and end boundaries.

<x-form.date model="travel_dates" range label="Travel Duration" />

Locales Support

Pass language codes to initialize localized date displays:

<x-form.date model="appointment_date" locale="el" label="Ημερομηνία" />

Native HTML Form Mode

If the model attribute is omitted, the date picker works as a plain form input writing to a hidden field for standard PHP POST requests.

• Single date mode: Submits to the input name parameter.
• Range date mode: Submits to [name]_start and [name]_end (e.g., if name="travel_dates", POST fields will be travel_dates_start and travel_dates_end).

{{-- Submits birth_date --}}
<x-form.date name="birth_date" label="Date of Birth" />

{{-- Submits hotel_dates_start and hotel_dates_end --}}
<x-form.date name="hotel_dates" range label="Hotel Booking" />

Disabled Inputs

The x-form.disabled component displays non-editable content in a clean, consistent format. It is equipped with quick-action wrapper tags that support instant interactivity without writing extra Javascript.

<x-form.disabled label="API Token" value="vkm_token_abcdef123456" copy />

Component Properties

Advanced Usage Examples

Display Currency Formatting: Prepend locale-aware currency symbols dynamically resolved from the ISO code.

<x-form.disabled label="Invoice Value" value="1,240.00" currency="USD" />

Custom Icon Overlay:

<x-form.disabled label="Status" value="Active" icon="fa-solid fa-circle-check" />

Prepend & Append Slots:

<x-form.disabled value="vasilis.milopoulos@gmail.com" mail>
    <x-slot:prepend><span class="text-xs text-gray-500">[Verified]</span></x-slot:prepend>
</x-form.disabled>

Money Input

A locale-aware, highly polished money input component built with AlpineJS masking (x-mask:dynamic). It formats user input dynamically with correct thousands and decimal separators based on locale and currency settings, while sending and maintaining a raw numeric float value to Livewire or traditional form submissions.

<x-form.money model="price" label="Unit Price" />

Key Features

1. Automatic Locale & Currency Resolution: Using PHP's NumberFormatter class, the component automatically resolves the decimal separator, thousands separator, currency symbol, symbol position (prefix vs. suffix), and default precision.
2. Dynamic Placeholders: If no explicit placeholder is provided, the component dynamically generates a formatted placeholder representing the currency format (e.g. 1,000.00 for en-US / USD, or 1.000,00 for de-DE / EUR).
3. Dual Bindings: A visible, styled text input handles the masked presentation using AlpineJS, while a hidden input stores the raw, unformatted float value (rawValue) for clean database storing and Livewire updates.
4. Livewire & Plain HTML Form Support: Integrates seamlessly with Livewire's binding modifiers (live, blur, change) and supports traditional form submissions using the name attribute.

Component Properties

Advanced Examples

Custom Currency & Locale: Explicitly define a different currency and locale. The input automatically positions the symbol (prefix or suffix) and formats numbers correctly.

{{-- German locale with Euro (symbol € placed as suffix, e.g. 1.000,00) --}}
<x-form.money model="price" label="Price" currency="EUR" locale="de-DE" />

{{-- US locale with GBP (symbol £ placed as prefix, e.g. £1,000.00) --}}
<x-form.money model="price" label="Price in Pounds" currency="GBP" locale="en-US" />

Custom Decimal Precision: You can specify custom decimal precision (e.g., for commodities, exchange rates, or precision pricing).

<x-form.money model="rate" label="Exchange Rate" precision="4" />

Rich Text Editor

An HTML WYSIWYG editor containing formatting tools, custom text and highlight colors, table structures, and links. It also has features for YouTube embeds, image sizing, and Livewire File Manager integrations.

<x-form.editor model="html_content" label="Rich Text Content" with-filemanager />

Component Properties

[!IMPORTANT] Singleton Table Editor Requirement To use the rich text editor's custom table builder, you must render the shared editor modal singleton once in your application's layout file (usually right before the closing </body> tag):

<x-form.editor-modal />

Reactive Array Updates

If you are updating dynamic models and arrays inside Livewire and need the text editor's HTML to stay reactive without breaking input focus, pass the identifier of the tracked array inside the watchFor property:

<x-form.editor model="item.content" :watchFor="$item['id']" label="Editable Item" />

File Upload

Allows users to upload files via standard buttons or high-fidelity, drag-and-drop dropzones.

<x-form.file model="attachment" label="Document Attachment" button="Choose File..." />

Component Properties

Dropzone Uploader

Adds a dashed drag-and-drop zone that supports drop events and file list displays.

<x-form.file
    model="attachments"
    label="Upload Gallery"
    dropzone
    multiple
    help="PNG, JPG or WEBP up to 5MB"
/>

File URL Browser

The x-form.file-url component combines a standard input field with the package's Livewire File Manager. Clicking the input allows the user to browse files inside their storage disk and attaches the selected file's public URL directly back to the text input.

<x-form.file-url model="avatar_url" label="Avatar Image URL" placeholder="Browse or paste URL..." />

Component Properties

Icon Helper

A lightweight, centralized Blade component that renders vector SVGs from the package's default icon directory. This avoids duplicating inline SVG codes throughout layouts.

<x-form.icon name="trash" class="text-red-500 size-6" />

Component Properties

Predefined Icon Names

The following keys are supported out-of-the-box:

paragraph, headings, textcase, fontsize, bold, italic, underline, strikethrough, superscript, subscript, code, textcolor, backgroundcolor, alignment, alignleft, aligncenter, alignright, ul, ol, letter_list, table, link, video, image, cleanup, chevron-up, chevron-down, chevron-left, chevron-right, settings, trash.

Customization

Publishing Component Views

If you need to tweak the HTML architecture of the inputs directly, publish the view files to your application directory:

php artisan vendor:publish --tag=x-form:views

The view files will be copied to resources/views/vendor/x-form/, allowing you to modify them without losing package update capabilities.

Custom Styling in config/x-form.php

The styling is completely driven by configuration values. You can change global background behaviors, focus states, sizes, and borders:

'inputs' => [
    'bg'      => 'bg-black/5 dark:bg-white/5 backdrop-blur-md shadow-xs',
    'border'  => 'border border-black/5 dark:border-white/10',
    'focus'   => 'focus:ring-2 focus:ring-blue-500/50 dark:focus:ring-blue-400/50 focus:shadow-md outline-none',
],

License

This package is open-sourced software licensed under the MIT license.