laravel-form-components

Introduction

Installation

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`

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:5.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, either by using your own views and specifying them in the config, or 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 built CSS in your own CSS files using @import '../../vendor/rawilk/laravel-form-components/resources/js/laravel-form-components-styles/dist/styles.css';. This is assuming your stylesheet is located in the ./resources/css/ directory of your project.

Directly in Blade/HTML

You could copy the built CSS from vendor/rawilk/laravel-components/resources/js/laravel-form-components-styles/dist/styles.css into your public folder, and then use a link tag in your blade/html to get it: <link rel="stylesheet" href="{{ asset('css/laravel-form-components.css') }}">.

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 and views 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 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.

Edit on GitHub
Previous
Requirements
Next
Upgrade