Introduction
Upgrade
- Upgrading from v8 to v8.1.0
- Upgrading from v7 to v8
- Upgrading from v6 to v7
- 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 v8 to v8.1.0
Although technically there is a breaking change in this version of v8, I've decided against bumping a major version number since the change does not affect functionality of the package.
Dark Mode
To allow for more flexibility for dark mode configuration in Tailwind, a new dark-mode
Tailwind plugin has been added, which you will need to add to your project's Tailwind config file.
If your app does not support dark mode, you don't need to worry about this change.
// tailwind.config.js
module.exports = {
plugins: [
// ...
require("./vendor/rawilk/laravel-form-components/resources/js/tailwind-plugins/dark-mode"),
],
};
The dark-mode.css
file has also been removed, so if you were manually pulling that into your stylesheets, you will need to remove the reference to it.
Upgrading from v7 to v8
Several breaking changes were introduced in v8. Please read the following carefully before upgrading. This list may not be fully comprehensive, so be sure to check the full changelog for all changes that have been made. Feel free to PR any important changes that may be missing in this upgrade guide.
Laravel Version
v8 of laravel-form-components now requires a minimum Laravel version of 9.0
. Be sure to update your project to at least that version.
Config
If you have the package's config file published, be sure to update it to be compatible with the new config. Here are some notable changes to the config file in v8:
-
components
is now just a simple key/value array of component aliases to class names. Any config to a component done here is now moved to thedefaults
key. -
defaults
has been added to allow setting default values for common component options. Be sure to refer to the config file for a complete list of available defaults. - the
assets
key has been removed, as the package will no longer load in 3rd party cdn assets anymore. Be sure to load them in yourself if you were relying on this in your project. - the
link_vendor_cdn_assets
key has also been removed.
Blade Directives
In v8, the package will no longer pull in 3rd party CDN assets for you anymore. We have removed the @fcScripts
and @fcStyles
directives, since they are not needed anymore. We have also
renamed the @fcJavaScript
directive to @fcScripts
. This directive will only load the JS that is written by the package to power some components.
If using a directive isn't your style, you may also us the new <fc:scripts />
self-closing tag to load in the package's JS.
Styling
If you were overriding component definitions to modify their styles, you may not need to do that anymore. In v8, we have removed any Tailwind classes from the markup in the components,
and are instead using @apply
in the package's CSS to apply the styles to custom class names. This should make it easier to override styles in your own project. Some custom class
names for components have changed as well, so if you are styling them in your own project, you will want to reference the component's markup to get the updated class names.
We've also introduced a number of CSS variables to our stylesheets, which you can override in your own project's CSS to customize many certain aspects of the components using variables instead. A full reference to the CSS variables can be found in the variables.css file.
Checkbox Group
The form-checkbox-group
CSS class is now always applied to the checkbox group component, whether it is stacked or not.
Custom Select/Tree Select
The custom select component has been re-written in v8. Here are some notable differences:
- Customizing option display in the menu has changed. See customizing the option display for more info.
- Customizing the selected option has changed. See customizing the selected option display for more info.
-
is_opt_group
has been deprecated for determining if an option is an "opt group" on custom-select. Provide a non-empty array of "children" on the option itself now. See Opt Groups for more info. - The
name-value-manually-updated
listener has been removed, as it's not needed. -
closeOnSelect
has been removed. The component will now automatically close on single selects, but stay open for multi-selects when selecting an option. - If you were rendering "opt groups" for custom select, you should not flatten your array of options anymore. Custom select will now determine opt groups by the presence of
children
on an option now.
Switch Toggle
The switch toggle component's markup has been simplified. It now uses a native checkbox input and a single div which relies on Tailwind's peer classes for styling. Some props, such
as $labelPosition
have been removed. Please refer to the component's documentation for a complete rundown of how to use it in v8.
FilePond
The way you define filepond callbacks has changed slightly. To define a callback now, you will want to use the config
slot. Inside the slot, you will have access to
three JS variables: instance
, options
, and pondOptions
. The instance
variable is the Alpine data object for the component, and the options
variable is the
options object that is passed to the component. Here's an example of how you could hook into Filepond's oninit
callback:
<x-slot:config> oninit() { console.log('init', instance); }, </x-slot:config>
If you were registering plugins in the plugins
slot, you will need to move that logic somewhere else, as we have removed this slot. See Plugins for more information.
The watch-value
attribute has been removed. Now any changes to a wire:model
value will always be picked up by the component.
Quill
Similar to the FilePond component, the way you define Quill callbacks and options has changed slightly. To define a callback now, you will want to use the config
slot. You will have
access to the instance
and quillOptions
variables. instance
is the Alpine data object for the component, and quillOptions
is the options object that is passed to the component.
Here is an example of how you could define a handler for a custom toolbar button:
<x-slot:config>
toolbarHandlers: { variables: function (value) { const cursorPosition =
this.quill.getSelection().index; this.quill.insertText(cursorPosition,
value); this.quill.setSelection(cursorPosition +value.length); }, },
</x-slot:config>
If you were listening for a quill-input
event to be dispatched from the component, you will need to change it to input
. If you are using x-model
to bind the value, you may
not need that listener at all since the component has changed how it dispatches and updates values in v8.
QuillOptions
A defaults
static constructor has been added to QuillOptions, which should always be used to when defining the Quill options you are using. If you are familiar with the
Password class in Laravel, this is similar to that. The defaults
constructor can be used in a service provider to define default options you always want to use for Quill.
Here's a quick example of how you could force the "bold" button to always be hidden in your AppServiceProvider.
public function boot()
{
\Rawilk\FormComponents\Dto\QuillOptions::defaults([
return (new \Rawilk\FormComponents\Dto\QuillOptions)->hideBold();
]);
}
Now when you go to use QuillOptions, you can just call QuillOptions::defaults()
, and the bold toolbar button will always be hidden.
The withToolbarButton
signature has changed in this configuration object. The $handler
parameter has been removed in favor of defining the handler in the config
slot
as shown above.
If you wanted to define a variables
toolbar button for config example above for Quill, you would do it like this:
QuillOptions::defaults()->withToolbarButton('variables', [
'Option 1',
'Option 2',
]);
Please refer to the Quill component documentation for more information on how to use this.
Datepicker
If you need to define custom flatpickr callbacks, you need to use the config
slot now. For example, if you need to define a custom callback for the onOpen
event
that is fired by flatpickr, you would do it like this:
<x-slot:config>
onOpen: function (selectedDates, dateStr, instance) { // do something here.
},
</x-slot:config>
See the callbacks section on date-picker for more information.
Form Group
The CSS class given to a form group when it is considered inline has changed to form-group--inline
.
The custom-select-label
prop has been removed. Form group will automatically give focus to custom selects now when the label is clicked on.
Timezone Region
The \Rawilk\FormComponents\Support\TimeZoneRegion
class has been deprecated in favor of the \Rawilk\FormComponents\Support\TimeZoneRegionEnum
class. If you are running Php 8.1 or higher,
it is recommended to update your code to use the enum class instead. If you are running an older version of Php, you can continue to use the old class, but it will be removed in a future
release.
File Upload
The file upload component now renders as a native file upload element instead of using a custom button. Because of this, the label
prop as been removed since the
text of a native file input is not customizable.
Trailing Addons
The trailing-addon
prop and slot will now behave like the leading-addon
prop on components, which will render the text inside a light gray background next to the input.
If you want to the text to be inside the input, use the trailing-inline-addon
prop/slot instead.
Inline Addon Padding
The inline-addon-padding
and trailing-addon-padding
props have been removed for all inputs. To customize the padding on either side of the input when an inline addon is present,
override either the --inline-addon-pl
or --inline-addon-pr
CSS variables instead. Refer to Inline Addon for more information.
Upgrading from v6 to v7
Laravel Version
v7 of laravel-form-components now requires a minimum Laravel version of 8.70
. Be sure to update your project to at least that version.
Styling
In v7 we have moved our styles to the resources/css
directory of this package to help simplify things a little. By default, all styles from
the package are imported into the index.css
stylesheet, which you can then reference in your own stylesheets. Be sure to update your stylesheet
reference to something like this:
@import "../../vendor/rawilk/laravel-form-components/resources/css/index.css";
Custom Select
The custom select component has been revamped in v7, and as a result some breaking changes were introduced. The following changes should be updated in your own codebase to continue using this component:
-
textField
is now calledlabelField
- The
valueField
andlabelField
default values have changed toid
andname
, respectively - The
min
andmax
props have changed tominSelected
andmaxSelected
, respectively - "Opt Group" options no longer need to contain the group's options, as they won't be rendered automatically. You should flatten your options to a single level now.
-
wire-listeners
is no longer included for updating dependant selects. Your dependant selects should be re-rendered to reflect an update to options now.
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.