Installation

Simply install the package using Composer:

composer require bgaze/bootstrap-form

There are a various configuration options available, publish the configuration file to customize them:

php artisan vendor:publish --provider="Bgaze\BootstrapForm\BootstrapFormServiceProvider"

That's it, you can start to build forms.
But if you use PhpStorm IDE, you can also check this gist to easily configure syntax highlighting and live templates for this package's custom Blade directives.

Quick start

The BF facade provides many methods to create forms and form inputs.
All of them have a Blade directive alias.

In this doc, we'll mainly use blade directives as it is probably the most common way to use BF.

Blade template:

@open(['novalidate' => true])
@text('login')
@email('email')
@checkbox('remember_me', null, 1, null, ['switch' => true, 'inline' => true])
@submit('Login')
@close

PHP code:

echo BF::open(['novalidate' => true])
echo BF::text('login')
echo BF::email('email')
echo BF::checkbox('remember_me', null, 1, null, ['switch' => true, 'inline' => true])
echo BF::submit('Login')
echo BF::close()

Bootstrap 5 support

Since v3.0, BF can render Bootstrap 5 markup.
Bootstrap 4 stays the default, so existing applications are not impacted until they explicitly opt in.

Application wide: set the version in the published configuration file.

// config/bootstrap_form.php
'bootstrap_version' => 5,

Per form: all the form's fields inherit the version.

@open(['url' => '/my/url', 'bootstrap_version' => 5])

Per field:

@text('login', null, null, ['bootstrap_version' => 5])

The version is resolved in this priority order: field > form > package configuration.

Behaviour differences with Bootstrap 4:

• Vertical and horizontal layouts are fully supported. Inline forms are best-effort: Bootstrap 5 reworked the inline layout and it may require additional markup on your side.
• The custom option is a no-op in Bootstrap 5, where custom controls were merged into the default styles.

Upgrading from v2 to v3

v3 is backward compatible at runtime: with the default bootstrap_version (4), the rendered HTML is unchanged. The only breaking change is the configuration file structure: the layout options (custom, left_class, right_class, pull_right, lspace, hspace, vspace) now live under per-version sections (bootstrap4 and/or bootstrap5).

If you had published and customized the configuration file, republish it and move your customizations under the bootstrap4 (and/or bootstrap5) key:

php artisan vendor:publish --provider="Bgaze\BootstrapForm\BootstrapFormServiceProvider" --force

Applications that never published the configuration file have nothing to do.

Forms

Creating forms

Open a form using BF::open() method, or @open() directive, which accepts an array of options as argument.
By default, a POST method will be assumed. However, you are free to specify another method.

Close the form using BF::close() method or @close directive.

@open(['route' => 'users.index', 'method' => 'GET', 'id' => 'users-search-form'])
<!-- Add your fields -->
@close

There is three ways to set the form action, priority order is: url > route > action

<!-- Using a URL -->
@open(['url' => 'foo/bar'])

<!-- Using a named route -->
@open(['route' => 'route.name'])

<!-- Using a controller action -->
@open(['action' => 'Controller@method'])

<!-- You may pass in parameters too -->
@open(['route' => ['route.name', $id]])
@open(['action' => ['Controller@method', $id]])

If your form is going to accept file uploads, add a files option to your array:

@open(['url' => 'foo/bar', 'files' => true])

Form options

Please find below available form options.
=> Any key that is not in form's options list will be used as HTML attribute.
=> Options take precedence on attributes. To use an option key as HTML attribute, prefix it with a ~.

Option	Default value	Accepted values	Description
files	null	null / true	Configure form enctype for file upload
url	null	string	A URL to use as form action Example: /foo/bar
route	null	string / array	A route to use as form action Example: users.update
action	null	string / array	A controller action to use as form action Example: UserController@update
store	null	string / array	The store action when using model binding
update	null	string / array	The update action when using model binding
model	null	Illuminate\Database\Eloquent\Model	A model to bind to the form
error_bag	'default'	string	The error bag to use for the form errors, useful when multiple forms exists on the same page.
bootstrap_version	Inherited 1	4 / 5	The Bootstrap markup version to render (see Bootstrap 5 support). Can also be overridden per field.
layout	Inherited 1	vertical / horizontal / inline	The Bootstrap layout of the form (doc)
group	Inherited 1	false / array	A set of HTML attributes for all the form groups (extends group package configuration)
custom	Inherited 1	bool	Use Bootstrap custom style by default when available
show_all_errors	Inherited 1	bool	Show all the errors of an input or just the first one
pull_right 2	Inherited 1	false / HTML class	Add an empty left column to checkboxes, radios and fields without label to preserve fields alignment
left_class 2	Inherited 1	string	The default width of left column
right_class 2	Inherited 1	string	The default width of right column
lspace 3	Inherited 1	false / HTML class	The horizontal blank space between labels and fields, doesn't apply to checkboxes and radios (CSS needed)
hspace 3	Inherited 1	false / HTML class	The horizontal blank space between fields
vspace 3	Inherited 1	false / HTML class	The vertical blank space between fields

1: Inherited from package configuration.
2: Horizontal layout only.
3: Inline layout only.

Note (v3): the configuration-level layout options — custom, left_class, right_class, pull_right, lspace, hspace, vspace — now live under the per-version bootstrap4 / bootstrap5 sections of the config file. custom is a no-op in Bootstrap 5 (see Bootstrap 5 support).

Form variations

BF supports the three Bootstrap form layouts: vertical, horizontal, inline.
The form layout can be set when opening form using the layout option.

BF provides helpers to open a form with a specific layout:

• BF::vertical() / @vertical()
• BF::horizontal() / @horizontal()
• BF::inline() / @inline()

They work exactly the same as BF::open() / @open() with the layout option forced.
Several options allow to adjust horizontal and inline layouts.

Vertical form

@vertical(['url' => 'some-url'])
@email('email')
@password('password')
@checkbox('remember_me', null, 1, null, ['switch' => true])
@submit('Login')
@close

Horizontal form

@horizontal(['url' => 'some-url'])
@email('email')
@password('password')
@checkbox('remember_me', null, 1, null, ['switch' => true])
@submit('Login')
@close

Custom horizontal form

@horizontal(['url' => 'some-url', 'pull_right' => false, 'left_class' => 'col-5', 'right_class' => 'col-7'])
@email('email')
@password('password')
@checkbox('remember_me', null, 1, null, ['switch' => true])
@submit('Login')
@close

Inline form

@inline(['url' => 'some-url'])
@email('email')
@password('password')
@checkbox('remember_me', null, 1, null, ['switch' => true])
@submit('Login')
@close

Custom inline form

@inline(['url' => 'some-url', 'lspace' => 'mr-3', 'hspace' => 'mr-5', 'vspace' => 'my-4'])
@email('email')
@password('password')
@checkbox('remember_me', null, 1, null, ['switch' => true])
@submit('Login')
@close

Model binding

Model binding allows you to populate a form based on a model attributes.
Fields will be populated with this priority: Session (Old Input) > Explicit value > Model attribute.

To open a model binded form, use the model option.
Passed value must be an instance of Illuminate\Database\Eloquent\Model otherwise it will be ignored.

<!-- Using a URL -->
@open(['model' => $user, 'url' => url('users/store')])

<!-- Using a named route -->
@open(['model' => $user, 'route' => 'users.store'])
@open(['model' => $user, 'route' => ['users.update', $user->id]])

<!-- Using a controller action -->
@open(['model' => $user, 'action' => 'UserController@store'])
@open(['model' => $user, 'action' => ['UserController@update', $user->id]])

If you provide store and update options, BF will automatically set form action and method based on model existence.
For update action, model route key will be automatically populated.

<!-- Using named routes -->
@open(['model' => $user, 'store' => 'users.store', 'update' => 'users.update'])

<!-- Using controller actions -->
@open(['model' => $user, 'store' => 'UserController@store', 'update' => 'UserController@update'])

<!-- You may pass parameters too, but remember that model route key will be added in last position -->
@open(['model' => $user, 'store' => ['users.store', $routeParameter], 'update' => ['users.update', $routeParameter]])
@open(['model' => $user, 'store' => ['UserController@store', $routeParameter], 'update' => ['UserController@update', $routeParameter]])

Form inputs

Creating inputs

Most of form input functions accept following four arguments:

name

The name of the field.
Unless they are explicitly provided, name will also be used as id attribute and as base for the form group id attribute.

label

The label of the field.
Please note that HTML escaping is disabled on labels to ease complex label creation.
If label is null, it will be generated based on name value.
If label is false, no label will be inserted.

value

The value of the field.
Field value is automatically evaluated with this priority:
Session (Old Input) > Explicit value > Model attribute (model binded forms only).
Most of times, you just need to set null as value.

options

An array of options.
Any value passed that is not in field options list will be used as HTML attribute.
Options take precedence on attributes, to use an option key as HTML attribute, prefix it with a ~.

<!-- Simple -->
@text('simple')

<!-- Disabled -->
@text('disabled', null, 'custom value', ['disabled' => true])

<!-- Custom -->
@text('custom', 'Custom', null, ['id' => 'custom-id', 'placeholder' => 'Enter a value'])

<!-- Help text -->
@text('help_text', 'Field with help text', null, ['help' => 'This is a help text'])

<!-- Custom form group -->
@text('custom_group', 'Custom form group', null, [
    'group' => [
        'id' => 'custom-group-id',
        'class' => 'p-2',
        'style' => 'border: 1px solid #ccc;'
    ]
])

<!-- No form group -->
@text('no_form_group', 'No form group', null, ['group' => false])

Common options

All input functions accept following options in addition to their specific ones:

Option	Default value	Accepted values	Description
help	false	false / string	Display a help text under the field (see doc)
group	Inherited 1	null / false / array	array: a set of HTML attributes for the form-group element (extends group form option). false: return the input element only.
layout 2	Inherited 1	vertical / horizontal / inline	The Bootstrap layout of the field
show_all_errors	Inherited 1	bool	Show all the errors of an input or just the first one
pull_right 3	Inherited 1	false / HTML class	Add an empty left column to checkboxes, radios and fields without label to preserve fields alignment
left_class 3	Inherited 1	string	The default width of left column
right_class 3	Inherited 1	string	The default width of right column
lspace 4	Inherited 1	false / HTML class	The horizontal blank space between label and field, doesn't apply to checkboxes and radios (CSS needed)
hspace 4	Inherited 1	false / HTML class	The horizontal blank space between fields
vspace 4	Inherited 1	false / HTML class	The vertical blank space between fields

1: Inherited from current form options, or package configuration if no opened form.
2: The layout option allows you to override the current context layout. For instance, you can add a horizontal form group into a vertical form. As this is not a planned Bootstrap feature, you'll probably need to adapt CSS accordingly.
3: Horizontal layout only.
4: Inline layout only.

Note (v3): the configuration-level options (pull_right, left_class, right_class, lspace, hspace, vspace) live under the per-version bootstrap4 / bootstrap5 sections of the config file (see Bootstrap 5 support).

Text inputs

Text inputs functions are:

• BF::text() / @text()
• BF::email() / @email()
• BF::url() / @url()
• BF::tel() / @tel()
• BF::number() / @number()
• BF::date() / @date()
• BF::time() / @time()
• BF::color() / @color()
• BF::textarea() / @textarea()
• BF::password() / @password()

Signature:

All these functions signature is the same, except password input that doesn't accept a value:

BF::text($name, $label = null, $value = null, array $options = [])
BF::password($name, $label = null, array $options = [])

Examples:

@text('text')
@email('email')
@url('url')
@tel('tel')
@number('number')
@date('date')
@time('time')
@color('color')
@textarea('textarea')
@password('password')

Options:

In addition to common options, following ones are accepted:

Option	Default value	Accepted values	Description
size	null	null / sm / lg	The size of the field (see doc)
append	false	false / string / array	An input group prefix (see Input groups for details)
prepend	false	false / string / array	An input group suffix (see Input groups for details)

Checkbox & radio

Single input:

Pass a boolean into checked argument to force input's checked state.

BF::checkbox($name, $label = null, $value = 1, $checked = null, array $options = [])
BF::radio($name, $label = null, $value = 1, $checked = null, array $options = [])

Single radios examples:

@radio('single_radio_default')
@radio('single_radio_custom', 'Custom radio', null, null, ['custom' => true])

Single checkboxes examples:

@checkbox('single_checkbox_default')
@checkbox('single_checkbox_custom', 'Custom checkbox', null, null, ['custom' => true])
@checkbox('single_checkbox_switch', 'Switch checkbox', null, null, ['switch' => true])

Inputs group:

choices

A value => label associative array defining group's inputs.
Example: [1 => 'Yes', 0 => 'No']

checked

An array containing the value(s) of checked input(s).
If only one input is checked, you can pass its value directly.

BF::checkboxes($name, $label = null, array $choices = [], $checked = null, array $options = [])
BF::radios($name, $label = null, array $choices = [], $checked = null, array $options = [])

Radios groups examples:

@radios('radios_default', null, ['L' => 'Large', 'S' => 'Small'])
@radios('radios_custom', null, ['L' => 'Large', 'S' => 'Small'], null, ['custom' => true])
@radios('radios_inline', null, ['L' => 'Large', 'S' => 'Small'], null, ['inline' => true])

Checkboxes groups examples:

@checkboxes('checkboxes_default', null, ['L' => 'Large', 'S' => 'Small'])
@checkboxes('checkboxes_custom', null, ['L' => 'Large', 'S' => 'Small'], null, ['custom' => true])
@checkboxes('checkboxes_switch', null, ['L' => 'Large', 'S' => 'Small'], null, ['switch' => true])
@checkboxes('checkboxes_inline', null, ['L' => 'Large', 'S' => 'Small'], null, ['inline' => true])

Options:

In addition to common options, following ones are accepted:

Option	Default value	Accepted values	Description
inline	false	bool	Create inline input(s) (doc)
custom	Inherited 1	bool	Create custom input(s) (doc). No-op in Bootstrap 5.
switch 2	false	bool	Create switch custom input(s) (doc)

1: Inherited from current form options, or package configuration if no opened form.
2: Checkbox inputs and groups only.

Select input

Signature:

choices

The input options as a value => label associative array: ['L' => 'Large', 'S' => 'Small'].
Options groups can be created using nested array: ['Cats' => ['leopard' => 'Leopard'],'Dogs' => ['spaniel' => 'Spaniel']]

checked

An array of selected option(s) value(s).
If only one option is selected, you can pass its value directly.

BF::select($name, $label = null, array $choices = [], $selected = null, array $options = [])

Default select examples:

@select('select_default', null, ['L' => 'Large', 'S' => 'Small'])
@select('select_multiple', null, ['L' => 'Large', 'S' => 'Small'], null, ['multiple' => true])
@select('select_optgroup', null, ['Cats' => ['leopard' => 'Leopard'], 'Dogs' => ['spaniel' => 'Spaniel']])

Custom select examples:

@select('select_custom', null, ['L' => 'Large', 'S' => 'Small'], null, ['custom' => true])
@select('select_custom_multiple', null, ['L' => 'Large', 'S' => 'Small'], null, ['custom' => true, 'multiple' => true])

Options:

In addition to common options, following ones are accepted:

Option	Default value	Accepted values	Description
custom	Inherited 1	bool	Create a custom select input (doc)
size	null	null / sm / lg	The size of the field (doc)
append	false	false / string / array	An input group prefix (see Input groups)
prepend	false	false / string / array	An input group suffix (see Input groups)

1: Inherited from current form options, or package configuration if no opened form.

File input

Custom file input requires additional JavaScript.
The recommended plugin is bs-custom-file-input.

Signature:

BF::file($name, $label = null, array $options = [])

Examples:

@file('file_default')
@file('file_custom', null, ['custom' => true])
@file('file_custom_text', null, ['custom' => true, 'text' => 'Choose a file', 'button' => 'Browse'])

Options:

In addition to common options, following ones are accepted:

Option	Default value	Accepted values	Description
custom	Inherited 1	bool	Create a custom file input (doc)
text 2	"Choose file"	string	The placeholder text
button 2	null	string	The button text
append 2	false	false / string / array	An input group prefix (see Input groups)
prepend 2	false	false / string / array	An input group suffix (see Input groups)

1: Inherited from current form options, or package configuration if no opened form.
2: Custom file inputs only.

Range input

See documentation for more details on range inputs usage.

Signature:

BF::range($name, $label = null, $value = null, array $options = [])

Examples:

@range('range_default')
@range('range_custom', null, null, ['custom' => true])
@range('range_minmax', null, null, ['min' => 0, 'max' => 10, 'step' => 0.5])

Options:

In addition to common options, following option is accepted:

Option	Default value	Accepted values	Description
custom	Inherited 1	bool	Create a custom range input

1: Inherited from current form options, or package configuration if no opened form.

Misc

Hidden input

This function is an alias to Form Builder function.
As for other inputs, id attribute based on field name will be added if missing

BF::hidden($name, $value = null, $options = [])

Examples:

@hidden('hidden_field')
@hidden('hidden_field_value', 'The hidden value')
@hidden('hidden_field_attributes', null, ['data-custom' => 'A custom data attribute'])

Input groups

For compatible input types, set append / prepend options to create a Bootstrap input group.
See documentation for details.

These options accept an HTML string, or an array of HTML strings, so you're free to build your field addons as you want.
Please note that provided HTML is not escaped.

Examples:

@text('input_groups_prepend', 'Prepend example', null, ['prepend' => '@@'])
@text('input_groups_append', 'Append example', null, ['append' => '.00'])
@text('input_groups_both', 'Both example', null, ['prepend' => '$', 'append' => '.00'])
@text('input_groups_array', 'Array example', null, ['prepend' => ['$', '0.'], 'append' => ['.00', '<button class="btn btn-outline-secondary" type="button">Button</button>']])

Label

This function is an alias to Form Builder function with escaping HTML disabled by default.

BF::label($name, $value = null, array $options = [], $escapeHtml = false)

Examples:

@label('label_field', 'Simple label')
@label('label_html_field', '<b>HTML label</b>')

Buttons

To create Bootstrap flavoured buttons, BF provides following helpers.

If you pass a string into the options argument, it will be prefixed by btn btn-.
If you pass an array, it will be merged into ['class' => 'btn btn-xxx'], with xxx the default button style.

Submit button:

Default style is primary.

BF::submit($value = null, $options = [])

Examples:

@submit()
@submit('Send')
@submit('Send', 'success')
@submit('Send', ['class' => 'btn btn-outline-primary'])

Reset button:

Default style is danger.

BF::reset($value = null, $options = [])

Examples:

@reset()
@reset('Reset form')
@reset('Reset form', 'warning')

Standard button:

Default style is primary.

BF::button($value = null, $options = [])

Examples:

@button('Click me')
@button('Click me', 'info')

Link button:

Default style is primary.

BF::link($url, $title = null, $options = [])

Examples:

@link('#', 'A link button')
@link('#', 'A link button', 'secondary')

Available methods & directives

Here is the list of available methods and directives.
Each directive is an alias to related BF facade method and works exactly like it.

If you use PhpStorm IDE, please check this gist to easily configure syntax highlighting and live templates for this package's custom Blade directives.

Facade methods	Blade directives	Description
BF::htmlBuilder()	-	Get the Laravel Collective HTML builder instance
BF::formBuilder()	-	Get the Laravel Collective form builder instance
BF::open()	@open()	Open a form (layout based on default configuration)
BF::vertical()	@vertical()	Open a vertical form
BF::inline()	@inline()	Open an inline form
BF::horizontal()	@horizontal()	Open a horizontal form
BF::close()	@close	Close a form
BF::text()	@text()	Create a text input
BF::email()	@email()	Create an email input
BF::url()	@url()	Create a URL input
BF::tel()	@tel()	Create a tel input
BF::number()	@number()	Create a number input
BF::date()	@date()	Create a date input
BF::time()	@time()	Create a time input
BF::color()	@color()	Create a color input
BF::textarea()	@textarea()	Create a textarea
BF::password()	@password()	Create a password input
BF::file()	@file()	Create a file input
BF::hidden()	@hidden()	Create a hidden input
BF::select()	@select()	Create a select input
BF::range()	@range()	Create a range input
BF::checkbox()	@checkbox()	Create a checkbox input
BF::checkboxes()	@checkboxes()	Create a checkboxes group
BF::radio()	@radio()	Create a radio input
BF::radios()	@radios()	Create a radios group
BF::label()	@label()	Create a label
BF::submit()	@submit()	Create a submit input
BF::reset()	@reset()	Create a reset input
BF::button()	@button()	Create a button
BF::link()	@link()	Create a link button