Introduction
Upgrade
{note} You're browsing the documentation for an old version of laravel-form-components. Consider upgrading your project to v8. Check your version with the following command:
composer show rawilk/laravel-form-components
Upgrading from v3 to v4
Version 4 introduced some breaking changes, which are outlined below:
Styling
In v4, laravel-form-components is now inlining a lot of the class names for form components instead of using @apply
in a stylesheet with a custom class name. For backwards compatibility, the custom class names are still included with each component to prevent breaking any style overrides you may have written.
Another major change with the styling is laravel-form-components now uses a single .css
stylesheet for any complex styles required instead of using .sass
stylesheets. This will allow the usage of postcss and/or tailwind's JIT compiler in your projects with these styles. If you're still using SASS, you should still be able to pull the styles in as you were before; you'll just need to update the path to the stylesheet.
In addition, we have stopped using the primary
and danger
variant names in favor of blue
and red
respectively. Be sure to update your tailwind config and stylesheets accordingly.
For more info on styling, please see the Customizing CSS section.
Added Dependencies
Some components, such as the custom-select
component, have a dependency on Popper.js
now for positioning the menu. This will require you to ensure that dependency is installed in your project. If you customized the package's configuration file, you should make sure you pull in any updates to the configuration as well.
See the custom select docs for more information.
Custom Select
One change for the custom-select component is it no longer has the fixed-position
attribute on it. It now relies on Popper.js for positioning the menu.
Form Group
One change for the form-group component is now all inline
form-groups now render a border above each group after the first group. If you do not want borders to be rendered on inline groups, be sure to set border
to false
:
<x-form-group label="My label" inline :border="false">...</x-form-group>
Another change is all form-groups have a mb-5
margin bottom utility class added by default for spacing. The last form-group element will have a sm:mb-0
utility class added to it so no extra margin is applied. You can prevent a margin from being added by setting the margin-bottom
attribute to false
:
<x-form-group label="My label" :margin="false">...</x-form-group>
{note} If you are using
space-y-*
utility classes for spacing, those will take precedence over the margin utilities added by the form-group component.
Upgrading from v2 to v3
The only major requirement for upgrading from v2 is to ensure your server and/or local dev environment is running on php version 8. As with any release,
you should make sure you are re-compiling your css assets (if pulling in the package's styles) and also clear your cached views (php artisan view:clear
)
to ensure the correct views are being used.
If you published the package's config file, make sure you update it to match any changes made to it.
Upgrading from v1 to v2
Version 2 introduced some breaking changes, which are outlined below:
Styling
To be compatible with TailwindCSS version 2, some changes were made to the stylesheets for laravel form components. There
were also some changes to how colors are referenced in both the blade templates and the sass files. V2 of laravel-form-components
is assuming you have the following variants configured in your tailwind.config.js
file:
const colors = require("tailwindcss/colors");
module.exports = {
// ...
theme: {
colors: {
"blue-gray": colors.blueGray,
},
extend: {
colors: {
primary: {
50: colors.blue["50"],
100: colors.blue["100"],
// continue all the way down to 900
},
danger: {
50: colors.red["50"],
// add keys for 50 - 900 as well
},
},
outline: {
"blue-gray": [`2px dotted ${colors.blueGray["500"]}`, "2px"],
},
},
},
};
The above configuration is just an example of what this package requires from your tailwind configuration. You are of course free to configure
your colors however you want to, as long as you have variants configured for primary
, danger
, and blue-gray
, and have the blue-gray
outline
defined as well. If you do not want to configure these colors, you will need to style the form components yourself.
For more information, please see the docs.
Custom Select
There have been major changes to the <x-custom-select>
component.
Options
Rendering options through the default slot is no longer supported. You must pass in options via the options
attribute for now on. "Optgroups" are now
specified by using the label
key on an option object, and must have an options
key on the object containing an array or collection of the group's options.
value-key
and text-key
If you were using custom keys for the values and text of the options, you will now need to change your attributes from value-key
to value-field
and
text-key
to text-field
respectively.
wire:filter
The wire:filter
attribute on the custom select has been changed to accept a method name from your livewire component instead. The livewire method
must return an array or collection of options.