laravel-form-components
Introduction
Upgrade
On this page
{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 v4 to v5
Alpine upgrade
The biggest breaking change in version 5 is changing support from alpine.js v2 to v3. This should require only minimal effort however in terms of updating the package. Based on the upgrade guide from Alpine.js, here is what you should need to do if you are importing Alpine from NPM:
import Alpine from "alpinejs";
window.Alpine = Alpine;
Alpine.start();
This won't affect you if you are using the CDN scripts from the configuration.
Additional stylesheet option
If you choose to import the compiled styles for this package into your own stylesheets, you can now import a minified stylesheet instead if you want to:
@import "../../vendor/rawilk/laravel-form-components/resources/js/laravel-form-components-styles/dist/styles.min.css";
See customizing css for more information.
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.