Laravel Form Components Library

A collection of pre-made simple Laravel Blade form components.

Installation & setup

You can install the package via composer:

composer require bjnstnkvc/form-components

The package will automatically register its service provider.

Usage

Config

Publish the components' config file with:

php artisan vendor:publish --provider="Bjnstnkvc\FormComponents\FormComponentsServiceProvider" --tag=form-config

This will publish a file called form_components.php in your config-directory.

Resources

Publish the components' resources files with:

php artisan vendor:publish --provider="Bjnstnkvc\FormComponents\FormComponentsServiceProvider" --tag=form-resources

This will publish a following files to a folder configured in form_components.php. By default, that folders is public/vendor/form-components. Detailed explanation for each property can be found here.

1. form-components.css
2. form-components.min.css
3. form-components.js
4. form-components.min.js

Directives

Once config and resources have been published, add following Blade directives to your layout file.

@componentStyles

@componentScripts

As the name of the directives suggests, these will add Form components minified CSS and JS files. In case you would like to edit published resource files, but would not like to edit minified versions, you can use the following syntax:

@componentStyles('full')

@componentScripts('full')

Directives above will instruct the library to load unminified css and js files, which you can edit as you see fit.

Form Components

In order to use the Form components, use standard [Blade Component syntax from the docs. By the default, the Form components can be used with the form prefix. Form components are using attributes which dictate how the component will be rendered.

Following attributes are worth mentioning:

• name - Name of the component (required).
• id - ID of the component (when not provided the name will be used).
• title - Title of the component (when not provided the name will be used).
• placeholder - Placeholder of the component (when not provided the name will be used).
• value - Value of the component, under the hood it makes use of the old() helper.
• label - Additional classes to be attached to the component label tag.
• label-type - Style in which the components are going to be displayed (by default, it's set to column).
• border - Border radius of the component (by default, it's set to rounded-s).
• border-radius - Border radius of the component (by default, it's set to rounded-s).
• invalidated-title - Determine whether the component title would change on invalid input (by default, set to false).
• show-icon - Determine whether the component icon errors should appear (by default, set to true).
• icon - Component icon in case show-icon property is set to true. Note that some components have a default icon set in form_components.php config file (more can be found here).
• interactive - Determine whether the validation errors should disappear on input (by default, set to false).

All other attributes wil be merged directly on to the HTML component element.

Base

<x-form::base method="PUT" action="{{ route('email.update') }}" >
    <x-form::email name="email" placeholder="Email placeholder" />
</x-form::base>

Depending on the method choice, component will automatically add _method token if needed.

Above will generate the following options:

<form class="fc-form" method="POST" action="http://form-components.com/email/update">
    <!-- CSRF Token -->
    <input type="hidden" name="_token" value="9G8i7aDB0loPj25Xwwm2Smosz3yjAhY3tOrvc6P3">
    <!-- Method Token -->
    <input type="hidden" name="_method" value="PUT">
    
    <label class="fc-form-group  tg-caption" label-type="column" for="email">
        <input class="form-group__input" placeholder="Email placeholder" type="email" id="email" name="email" value="" border="bottom" border-radius="rounded-s" with-icon="true" invalidated-title="false" interactive="false">
        <span class="form-group__title ">Email</span>
    </label>
</form>

Note that by default, Form Base component method attribute is set to POST.

Input

<x-form::input name="input" placeholder="Input placeholder" />

Depending on the label-type choice, component will look as follows:

label-type="column"	label-type="row"	label-type="floating"

In case the field was not valid, depending on the label-type choice, component will look as follows:

label-type="column"	label-type="row"

Password

<x-form::password name="password" placeholder="Password placeholder" />

Depending on the label-type choice, component will look as follows:

label-type="column"	label-type="row"	label-type="floating"

In case the field was not valid, depending on the label-type choice, component will look as follows:

label-type="column"	label-type="row"

Password components comes with 'Password Visibility' feature which is by default turned on.

In case you'd like to disable it, add password-visibility="false" to the component. Alternatively, you can disable this feature for all password fields through the project by setting password_visibility to false in your published form_components.php file.

Email

<x-form::email name="email" placeholder="Email placeholder" />

Depending on the label-type choice, component will look as follows:

label-type="column"	label-type="row"	label-type="floating"

In case the field was not valid, depending on the label-type choice, component will look as follows:

label-type="column"	label-type="row"

Search

<x-form::search name="search" placeholder="Search placeholder" />

Depending on the label-type choice, component will look as follows:

label-type="column"	label-type="row"	label-type="floating"

Search components comes with 'Search Clearing' feature which is by default turned on.

In case you'd like to disable it, add search-clearing="false" to the component. Alternatively, you can disable this feature for all Search fields through the project by setting search_clearing to false in your published form_components.php file.

Textarea

<x-form::textarea name="textarea" placeholder="Textarea placeholder" />

Depending on the label-type choice, component will look as follows:

label-type="column"	label-type="row"	label-type="floating"

In case the field was not valid, depending on the label-type choice, component will look as follows:

label-type="column"	label-type="row"

Textarea component comes with an option to auto-expand when typing which is by default turned off. In order to have it enable, use the following syntax:

<x-form::textarea name="textarea" placeholder="Textarea placeholder" autoexpand="true" />

Depending on the label-type choice, component will display following behaviour:

label-type="column"	label-type="row"

In case you wish auto expansion to be a default behaviour for all Textarea components, set auto_expand to true in your published form_components.php file.

Select

<x-form::select name="select" />

The Select components accept string or an array as value from which it'll construct select options.

In order to pass values as a string, use the following syntax:

<x-form::select name="select" values="Option A, Option B" />

Above will generate the following options:

<option value="option-a">Option A</option>
<option value="option-b">Option B</option>

In case you would like to pass option value as well as it's key, use the following syntax:

<x-form::select name="select" values="1: Option A, 2:Option B" />

Above will generate the following options:

<option value="1">Option A</option>
<option value="2">Option B</option>

Same rules apply in case you are passing an array. For example, following PHP array:

$options = ['Option A', 'Option B'];

and following blade component settings:

<x-form::select name="select" :values="$options" />

will generate the following options:

<option value="0">Option A</option>
<option value="1">Option B</option>

Note that due to the fact that an array was NOT passed as key => value, option value is starting from 0 and incrementing for each item.

In case an array has key => value pairs, following array:

$options = [
    1 => 'Option A', 
    2 => 'Option B'
];

will generate following HTML:

<option value="1">Option A</option>
<option value="2">Option B</option>

You can also pass whole Eloquent Model to the component. Let's say we have users table with the following data:

id	first_name	last_name	email
1	John	Doe	john.doe@example.com
2	Jane	Does	jane.does@example.com

passed from the controller:

return view('welcome', [
    'users' => User::all();
]);

In order to use it with Select component, following syntax is used:

<x-form::select name="select" :model="$users" model-key="id" model-value="first_name" />

As can be seen in an example above, in case Eloquent model has been passed, Select component expects three properties:

1. :model - Model passed from the controller or injected directly into the blade file.
2. model-key - Model key that will be used as an option value (when not provided the id will be used).
3. model-value - Model value from which option text will be generated.

<option value="1">John</option>
<option value="2">Jane</option>

In case you would like to pass JavaScript Data Set attribute to each generated option, use the following Blade Component attributes:

1. js-data-key - The attribute key.
2. js-data-value - The attribute value.

Note that the js-data-value attribute MUST match the Eloquent Model attribute name.

<x-form::select name="select" :model="$users" model-key="id" model-value="first_name" js-data-key="last-name" js-data-value="last_name" />

This will generate following HTML:

<option value="1" data-last-name="Doe">John</option>
<option value="2" data-last-name="Does">Jane</option>

Same as with the other components, placeholder can be passed to the component which will generate placeholder option value.

<x-form::select name="select" placeholder="Select a user" :model="$users" model-key="id" model-value="first_name" />

will generate following HTML:

<option value="">Select a user</option>
<option value="1">John</option>
<option value="2">Jane</option>

In order to set default select value, you can use default property, which will pre-select the option on component render. For example:

<x-form::select name="select" placeholder="Select a user" :model="$users" model-key="id" model-value="first_name" default="Jane" />

will generate following HTML:

<option value="">Select a user</option>
<option value="1">John</option>
<option value="2" selected>Jane</option>

Depending on the label-type choice, component will look as follows:

label-type="column"	label-type="row"	label-type="floating"

In case the field was not valid, depending on the label-type choice, component will look as follows:

label-type="column"	label-type="row"

Date

<x-form::date name="date"/>

Depending on the label-type choice, component will look as follows:

label-type="column"	label-type="row"	label-type="floating"

In case the field was not valid, depending on the label-type choice, component will look as follows:

label-type="column"	label-type="row"

Time

<x-form::time name="time" />

Depending on the label-type choice, component will look as follows:

label-type="column"	label-type="row"	label-type="floating"

In case the field was not valid, depending on the label-type choice, component will look as follows:

label-type="column"	label-type="row"

Date-Time

<x-form::date-time name="date & time" />

Depending on the label-type choice, component will look as follows:

label-type="column"	label-type="row"	label-type="floating"

In case the field was not valid, depending on the label-type choice, component will look as follows:

label-type="column"	label-type="row"

Date, Time and Date-Time components utilize built-in HTML elements.

Clicking on the component icon will open native browser Input UI.

Additionally, you can pass a value to all three fields which utilizes Carbon behind the scenes in order to parse the value prior to rendering the component.

File

<x-form::file name="file" placeholder="File placeholder" />

Depending on the label-type choice, component will look as follows:

label-type="column"	label-type="row"	label-type="floating"

In case the field was not valid, depending on the label-type choice, component will look as follows:

label-type="column"	label-type="row"

File component utilize built-in HTML element.

Checkboxes and Radio Buttons

Checkbox

<x-form::checkbox name="checkbox" />

Depending on the position choice, component will look as follows:

position="left"	position="center"

In case the field was not valid, depending on the position choice, component will look as follows:

position="left"	position="center"

Radio

<x-form::radio name="radio" />

Depending on the position choice, component will look as follows:

position="left"	position="center"

In case the field was not valid, depending on the position choice, component will look as follows:

position="left"	position="center"

Switch

Alternatively, if you set switch attribute to true to Checkbox or Radio component, it will look as follows:

Checkbox	Radio

Checked

Both Checkbox and Radio component come with checked attribute that expects boolean. Depending on the result, component will be renders as checked.

<x-form::checkbox name="checkbox" checked="{{ 2 + 2 == 4 }}" />

<x-form::radio name="radio" checked="{{ ! 2 + 2 === 4 }}" />

Buttons

Button

In order to render a Button component, use the following syntax:

<x-form::button name="login" />

The component utilizes Laravel Slots, so in case you need to inject HTML into the button, use the following syntax:

<x-form::button> Button Content </x-form::button>

Additionally, in case you'd like the form button to actually be a link, all you need to do is add link property to the component.

<x-form::button title="Login" link="login" />

Above property will render the component as an anchor tag.

Depending on the border-radius choice, component will look as follows:

border-radius="squared"	border-radius="rounded-s"	border-radius="rounded-m"	border-radius="rounded"

Border

All components come with two different border styles, full and bottom. In order to change component border style, add border property equal to one of the options listed above to your component of choice.

If you'd like to set a certain border style by default for all components, simply change component_border in your published form_components.php file.

Depending on the label-type choice, component will look as follows:

label-type="column"	label-type="row"	label-type="floating"

Border Radius

All components come with three different border radius styles, squared, rounded-s, rounded. In order to change component border radius style, add border-radius property equal to one of the options listed above to your component of choice.

If you'd like to set a certain border radius style by default for all components, simply change component_radius property in your published form_components.php file.

border-radius="squared"	border-radius="rounded-s"	border-radius="rounded"

Invalidated Title

All components are shipped with an ability to highlight component title in case the filed was invalid. In order to turn this feature on, add invalidated-title="true" to your component of choice.

If you'd like this feature to be turned on by default for all components, simply change invalidated_title property in your published form_components.php file.

label-type="column"	label-type="row"	label-type="floating"

Interactivity

All components are shipped with an ability to remove validation errors on input. In order to turn this feature on, add interactive="true" to your component of choice.

If you'd like this feature to be turned on by default for all components, simply change interactive property in your published form_components.php file.

Customisation

Config

• publish_path - Path used to publish component files.

• prefix - Form Components prefix, defaults to 'form' (E.g. ).

• separator - Form Components separator, defaults to '::' (E.g. x-form::button).

• label_type - Form Components label style, defaults to 'column' (options: column, row, floating).

• radius - Form Components default border radius (options: squared, rounded-s, rounded).

• icon - Form Components default icon visibility state.

• position - Form Components default checkbox/radio position, defaults to 'center' (options: left, center).

• switch - Determine whether the checkbox/radio components should be displayed as a switch.

• button_radius - Form Components default button radius (options: squared, rounded-s, rounded-m, rounded).

• invalidated_title - Determine whether the Component title would change on invalid input.

• password_visibility - Determine whether the password visibility button is rendered.

• search_clearing - Determine whether the search clearing button is rendered.

• auto_expand - Determine whether the Text Area height should expand with input.

• interactive - Determine whether the errors should disappear on input.

• image_formats - List of image formats to be rendered as tag

  • Example 1 : svg format IS part of the array, component icon will be rendered as <img src="..."> tag.
  • Example 2 : svg format is NOT part of the array, component icon will be rendered as <svg>...</svg> tag.

• default_icons - List of default icons for each component.

Note: You might need to clear config cache using php artisan cache:clear command after you make changes to .env file.

Publishing

You can publish all components class and view using artisan the following command:

php artisan components:publish

Optionally, you can pass component name as an argument, which will publish only those components.

php artisan components:publish Input Password Button

From this point on, you can change the published component class and view to your liking.

Restoring

If by any chance you'd like to restore the components default settings, use the following artisan command:

php artisan components:restore

Optionally, you can pass component name as an argument, which will restore only those components.

php artisan components:restore Input Password Button

Additionally, if you'd like to remove previously published components class and views, you can attach --delete option:

php artisan components:restore --delete

or

php artisan components:restore Input Password Button --delete

Note: You might need to clear config cache using php artisan cache:clear command after you publish or restore the components.

License

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