Download the PHP package okipa/laravel-form-components without Composer

Save time and take advantage of a set of dynamical, ready-to-use and fully customizable form components.

Components are Livewire compatible and can be used with the following UI frameworks:

• Bootstrap 5
• Bootstrap 4
• TailwindCSS 3 (upcoming feature)

Found this package helpful? Please consider supporting my work!

Compatibility

Upgrade guide

• From okipa/laravel-bootstrap-components to okipa/laravel-form-components

Usage example

Just call the components you need in your views and let this package take care of the HTML generation time-consuming part.

And get these components displayed:

Table of Contents

• Installation
• Configuration
• Views
• Components
  • Form
  • Input
  • Textarea
  • Select
  • Checkbox
  • Switch
  • Radio
  • Buttons
• How to
  • Deal with attributes and classes
  • Set id
  • Manage label and placeholder
  • Handle floating label displaying
  • Set addons
  • Bind data
  • Set custom value
  • Handle validation statuses and errors
  • Add captions
  • Activate multilingual mode
  • Plug with livewire
• Testing
• Changelog
• Contributing
• Credits
• Licence

Installation

You can install the package via composer:

Configuration

You can publish the config file with:

Among its configurations, this package allows you to choose which UI framework will be use.

Please note that you'll have to install and configure the UI framework you want to use before using this package.

Views

You can publish the package views to customize them if necessary:

Components

Form

Components can be wrapped into a form component.

If no custom method is set, a GET method will be set by default.

Hidden CSRF and spoofing method fields will be automatically generated when needed, according to the defined form method :

• You won't need to define a @method() directive, declare your PUT, PATCH or DELETE action directly in the action attribute
• You won't need to define a @csrf() directive, it will be automatically declared with POST, PUT, PATCH and DELETE actions

Forms are generated with a default novalidate HTML attribute, which is preventing browser validation in favor of a server-side validation (which is a good practice for security matters).

Input and Textarea

Add inputs and textarea into your forms.

If you don't set a custom type to an input, it will take a default text type.

Radio, checkbox and button inputs must be used with their own components because of their different behaviour.

Textarea component can be used the same way as an input component but without declaring a type.

Select

Set select components in your forms.

Auto generate options by providing an associative value/label array.

HTML select elements natively don't accept placeholder attributes, however the select component allows you to handle a placeholder-like option is prepended to the other ones. This placeholder will behave as for the other components.

By default, this select placeholder option is selected, disabled and hidden. However, you'll be able to allow it to be selected in case you need to set a nullable field for example. To do that, just add the allowPlaceholderToBeSelected attribute to your component.

In multiple mode, this package will take care about converting the name into an array name, so you don't have to add it manually.

Checkboxes, Toggle switches and Radios

Checkbox, toggle switch and radio components are available for you to use.

Because radio inputs are never used alone, you'll have to declare a required group attribute when using them, awaiting a value/label associative array from which the radio fields will be generated.

Regarding checkbox and toggle switch inputs, you will be able to use them in single or in group mode. To use them in group mode, you'll have to declare a group attribute too.

In group mode, this package will take care about converting the name into an array name, so you don't have to add it manually.

If you want to display these input components inline, just define an inline attribute.

Buttons

Submit and link button components are available.

Submit button allows you to trigger a form and will provide a default __('Submit') body if none is defined.

Link button allows you to set actions like Back or Cancel in your forms by providing a link with a button-like display. As this component is an HTML link, it will provide a default title by analysing its body.

By default, both components will set a base background color if no custom class attribute is defined.

How to

Deal with attributes and classes

Provided component are built using Blade components.

Following how Blade components work, you can set any HTML attributes and classes:

• Attributes will replace default ones
• Classes will be merged to existing ones

Set id

Define components ids as you would do for any HTML element.

If no custom id is set, an id will be generated using the kebab cased <type>-<name> values.

Enable or disable inputs margin bottom

By default, all input components will declare a bottom margin in order to correctly position themselves in a form.

You'll sometimes need to disable this default bottom margin: you'll can do this by setting the marginBottom attribute to false.

Manage label and placeholder

You can define labels on all input components (except for Radio).

If no custom label is defined, labels will take the __('validation.attributes.<name>) default value.

Following the same behaviour, all input components that are allowing the use of a placeholder (Select included) will provide a default placeholder that will take the label value.

You can override this default value by setting a custom placeholder.

You also can hide auto-generated label and placeholder by them to false.

Handle floating label displaying

This package allows you to enable or disable floating labels displaying.

You can set the global floating label behaviour with config('form-components.floating_label') config.

You will be able to override this global behaviour at form level for all contained components.

Finally, you'll also can override all other defined behaviour on components themselves.

Set addons

You can define prepend and append HTML addons on input and textarea components.

Note: you may use HTML directly instead of components for complex addon's management.

Bind data

You can bind Eloquent Models, objects, collections or arrays in order to autofill bound components values.

Binding data on the form component will trigger the binding of all of its contained components.

You can bind data directly on a component and override the form binding.

In case of validation error, components will be repopulated by old values that will override bound values.

For specific use case, you also can use the @bind($boundDataBatch) and the @endbind Blade directives to bind a group of components.

Set custom value

Data binding can be overridden by setting custom values on components.

Handle validation statuses and errors

Components will be able to display or hide their success/error statuses and error message when a validation error is triggered:

• If the validation success displaying is activated, components will only be marked as valid when other components in the form are detected as invalid
• If the validation failure displaying is activated, components in error will be marked as invalid and will display their related error message

You can control this behaviour at different levels:

• Define the global default behaviour with config('form-components.display_validation_success') and config('form-components.display_validation_failure')
• Customize this behaviour on a form and apply it locally for all its contained components
• Set a specific behaviour directly on a component

You also can customize the error bag that should be used to determine components success/error statuses and error messages on form components.

Add captions

Help users and display additional instructions under you components by adding captions.

Activate multilingual mode

Activate multilingual mode on input and textarea components to benefit from the following features:

• Component duplication: one component per locale will be displayed
• Name localization: name="description" will be transformed into name="description[<locale>]"
• Default label and error message localization: __(validation.attributes.name) translation used to generate default label and error message will be appended with (<LOCALE>)

Plug with Livewire

Form and input components are Livewire-compatible.

Instead of defining a wire:model HTML attribute on each component you want to wire as you would do without this package, here you'll just have to define a wire="<optional-modifier>" HTML attribute to make this work.

Each wired input component will use its own name attribute and convert it to a valid wire:model="<name>" one.

Following the same logic, you also can wire input components directly from the form they are contained into.

For specific use case, you also can use the @wire($modifier) and the @endwire Blade directives to wire a group of components with a specific Livewire modifier.

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Arthur LORENT
• All Contributors

License

The MIT License (MIT). Please see License File for more information.