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 v5 to v6
- Upgrading from v4 to v5
- Upgrading from v3 to v4
- Upgrading from v2 to v3
- Upgrading from v1 to v2
Upgrading from v5 to v6
Laravel Version
v6 of laravel-form-components now requires a minimum Laravel version of 8.56
. Be sure to update your project to at least that version.
Overriding component views
In v6, you must publish any package views you want to override instead of specifying a different view in the config. This was done to help
simplify the package config and how the base BladeComponent
class determines the view to render. You are still free to override any
component classes in the config, however.
New Component Namespace
Not a breaking change, but the package now defines the form-components
namespace in addition to providing aliases for each component
in the config. You will now be able to reference components either as <x-form>
or as <x-form-components::form>
if you choose to.
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.