Introduction

Upgrade

Table of Contents

{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 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 called labelField
  • The valueField and labelField default values have changed to id and name, respectively
  • The min and max props have changed to minSelected and maxSelected, 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.

Previous
Installation
Next
Questions & Issues
Caught a mistake? Suggest an edit on GitHub