bjnstnkvc/form-components

Simple Laravel Form components


Keywords
laravel
License
MIT

Documentation

Laravel Form Components Library

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

Laravel 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

@componentStyles

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')

@componentStyles('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.

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"
Input Column Label Type Input Row Label Type Input Float Label Type

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

label-type="column" label-type="row"
Input Column Label Error Input Row Label Error

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"
Password Column Label Type Password Row Label Type Password Float Label Type

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 Column Label Error Password Row Label Error

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

Password Visibility

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"
Email Column Label Type Email Row Label Type Email Float Label Type

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

label-type="column" label-type="row"
Email Column Label Error Email Row Label Error

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 Column Label Type Search Row Label Type Search Float Label Type

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

Search Clearing

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"
Textarea Column Label Type Textarea Row Label Type Textarea Float Label Type

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 Column Label Error Textarea Row Label Error

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"
Textarea Column Auto Expand Textarea Row Auto Expand

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 Doe jane.doe@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.

This will generate following HTML:

<option value="1">John</option>
<option value="2">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"
Select Column Label Type Select Row Label Type Select Float Label Type

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

label-type="column" label-type="row"
Select Column Label Error Select Row Label Error

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"
Date Column Label Type Date Row Label Type Date Float Label Type

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 Column Label Error Date Row Label Error

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"
Time Column Label Type Time Row Label Type Time Float Label Type

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 Column Label Error Time Row Label Error

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"
DateTime Column Label Type DateTime Row Label Type DateTime Float Label Type

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

label-type="column" label-type="row"
DateTime Column Label Error DateTime Row Label Error

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"
File Column Label Type File Row Label Type File Float Label Type

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 Column Label Error File Row Label Error

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"
Checkbox Position Left Checkbox Position Center

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

position="left" position="center"
Checkbox Position Left Error Checkbox Position Center Error

Radio

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

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

position="left" position="center"
Radio Position Left Radio Position Center

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

position="left" position="center"
Radio Position Left Error Radio Position Center Error

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"
Button Squared Button Rounded Small Button Rounded Medium Button 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 Bottom Column Border Bottom Row Border Bottom 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"
Border Radius Squared Border Radius Rounded Small 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"
Invalidated Title Column Label Type Invalidated Title Row Label Type Invalidated Title Float Label Type

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.

Input Interactivity

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).

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

  • component_icons - Form Components default icon visibility state.

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

  • 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.