Introduction

Installation

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

Notice

Most of the components in this package are based on examples from Tailwind UI. I have my own license for Tailwind UI, but you might not have one. Please do not use this package in your own projects without purchasing a Tailwind UI license, or they'll have to tighten up the licensing and you'll ruin the fun for everyone.

Purchase a license here: https://tailwindui.com/

Installation

You can install the package via composer:

composer require rawilk/laravel-form-components:7.0

Configuration

You may publish the config file via:

php artisan fc:publish

Click here to view the default configuration.

Directives

One of the biggest advantages to laravel-form-components is that almost all of its components come ready out-of-the-box. To achieve this, Laravel Form Components makes use of CDNs from any 3rd party library that a component might need. To make sure these CDNs are included in your HTML, you can make use of the @fcStyles and @fcScripts directives.

Place the @fcStyles in the <head> before any of your other styles. Place the @fcScripts directive right before your closing </body> tag and after scripts from libraries like Livewire.

{note} The @fcStyles directives does not include styles generated by Laravel Form Components. You will still need to include those in a stylesheet manually.

If you would like to only link to the JavaScript necessary for some package components, such as the custom select component, you may use the @fcJavaScript blade directive instead of @fcScripts. This is useful if you are compiling any third-party scripts yourself, and is recommended in production. You should not use both directives together regardless of how you choose to compile scripts.

Production

Even though these directives allow you to get up and running with the components quickly, we recommend that you compile the 3rd party libraries that each component needs through an asset pipeline (like Laravel Mix). By default, when your app.debug config option is disabled, the directives are also disabled for performance reasons.

If you always want these directives to be executed, even when app.debug is disabled, you can force them to load the CDN links by passing a true boolean:

@fcStyles(true) @fcScripts(true)

Libraries are only loaded for components that are enabled through the components config option. You can learn more about disabling specific components below.

Views

You may override the views, by publishing the package's views:

php artisan fc:publish --views

{note} This will also publish the package's configuration as well.

Styling

You have a couple options for how you can use the UI components' CSS, depending on you and your project's needs:

Using Laravel Mix or Webpack with CSS-Loader

You can import the CSS files into your own stylesheets using @import '../../vendor/rawilk/laravel-form-components/resources/css/index.css';'. This is assuming your stylesheet is located in the ./resources/css/ directory of your project.

This will import all the package's styles into your project, however you are free to import only the stylesheets you need as well. They are all located in the same directory as the index.css stylesheet.

If you would like to customize the CSS we provide, head over to the section on Customizing CSS.

{tip} If you are using Purge CSS or Tailwind's JIT compiler, you should check out the section on Purge CSS to prevent styles from being lost in production or at compile time.

Components

Even though all components come enabled out-of-the-box, you might just want to only load the components you need in your app for performance reasons. To do so, first publish the config file, then remove the components you don't need from the components settings.

You can also choose to use different classes for components. This allows you to either extend or completely change the component's functionality by using a custom class and/or view of your own.

Component Namespace

New in v6, the package also declares a form-components blade component namespace. This means that for any component you may also use the <x-form-components::component-name> syntax. For the input component, you would use <x-form-components::inputs.input />. If you choose to render the components using this method, you can safely remove the component alias from the config, however there are two caveats to this:

  1. You may not be able to override the component class definition any more if you remove the alias from the config.
  2. Some components have an array of configuration options attached to their alias. Those arrays are referenced by the component, so these aliases should not be removed or renamed.

Component JavaScript

Some components, such as the custom select component, require custom JavaScript to run. The JavaScript is extracted to an external file since it is pretty substantial and should be minified. If you are using any components that depend on this JavaScript, be sure you are pulling the scripts in through either the @fcJavaScript or @fcScripts blade directives in your layout file. See directives for more information.

JavaScript Dependencies

For any external JavaScript dependency, we recommend you install them through npm or yarn, and then require them in your project's JavaScript. To install each of the dependencies this package makes use of, run this command in the terminal:

npm install -D alpinejs @popperjs/core filepond flatpickr

{tip} You can pick and choose which dependencies you need to install based on which components your project is actually using.

In your JavaScript, add the following lines to pull each of the external dependencies you previously installed in:

import Alpine from "alpinejs";
import flatpickr from "flatpickr";
import * as FilePond from "filepond";
import { createPopper } from "@popperjs/core";

window.flatpickr = flatpickr;
window.FilePond = FilePond;
window.createPopper = createPopper;
window.Alpine = Alpine;

Alpine.start();

Dependency Styling

Some of the dependencies this package has also have their own styling they provide. If you followed the directions above for installing the JavaScript, you can easily pull in their styles into your project as well:

/* app.css */
@import "filepond/dist/filepond.min.css";
@import "flatpickr/dist/flatpickr.min.css";

{note} Be sure to include these styles above the styles for this package so any overrides this package uses for the dependencies gets applied correctly.

Asset URL

For cases where your app's root domain is not the correct path for retrieving assets, you may set a custom root path that FormComponents will use to link to its JavaScript assets. You may specify a custom root path either in the config file, or as a parameter option through the blade directive:

In the config:

[
    // ...
    'asset_url' => 'myapp.com/app',
];

In your layouts:

@fcJavaScript(['asset_url' => 'myapp.com/app'])
<!-- or -->
@fcScripts(false, ['asset_url' => 'myapp.com/app'])

Prefixing

Using components from this library might conflict with other ones from a different library or components from our own app. To prevent this you can opt to prefixing FormComponents components by default to prevent these collisions. You can do this by setting the prefix option in the config file:

<?php

return [
    // ...
    'prefix' => 'tw',
    // ...
];

Now all components can be referenced as usual but with the prefix before their name:

<x-tw-form action="http://example.com" />

For obvious reasons, the docs don't use any prefix in their code examples. So keep this in mind when setting a prefix and copying/pasting code snippets.

Previous
Requirements
Next
Upgrade
Caught a mistake? Suggest an edit on GitHub