Installation

The Widgets package is pre-installed with the Panel Builder. This guide is for using the Widgets package in a custom TALL Stack application (Tailwind, Alpine, Livewire, Laravel).

Requirements

Filament requires the following to run:

PHP 8.1+
Laravel v10.0+
Livewire v3.0+

Require the Widgets package using Composer:

composer require filament/widgets:"^3.2" -W
composer require filament/widgets:"^3.2" -W

New Laravel projects

To quickly get started with Filament in a new Laravel project, run the following commands to install Livewire, Alpine.js, and Tailwind CSS:

Since these commands will overwrite existing files in your application, only run this in a new Laravel project!

php artisan filament:install --scaffold --widgets
 
npm install
 
npm run dev
php artisan filament:install --scaffold --widgets

npm install

npm run dev

Existing Laravel projects

Run the following command to install the Widgets package assets:

php artisan filament:install --widgets
php artisan filament:install --widgets

Installing Tailwind CSS

Run the following command to install Tailwind CSS with the Tailwind Forms and Typography plugins:

npm install tailwindcss @tailwindcss/forms @tailwindcss/typography postcss postcss-nesting autoprefixer --save-dev
npm install tailwindcss @tailwindcss/forms @tailwindcss/typography postcss postcss-nesting autoprefixer --save-dev

Create a new tailwind.config.js file and add the Filament preset (includes the Filament color scheme and the required Tailwind plugins):

import preset from './vendor/filament/support/tailwind.config.preset'
 
export default {
    presets: [preset],
    content: [
        './app/Filament/**/*.php',
        './resources/views/filament/**/*.blade.php',
        './vendor/filament/**/*.blade.php',
    ],
}
import preset from './vendor/filament/support/tailwind.config.preset'

export default {
    presets: [preset],
    content: [
        './app/Filament/**/*.php',
        './resources/views/filament/**/*.blade.php',
        './vendor/filament/**/*.blade.php',
    ],
}

Configuring styles

Add Tailwind's CSS layers to your resources/css/app.css:

@tailwind base;
@tailwind components;
@tailwind utilities;
@tailwind base;
@tailwind components;
@tailwind utilities;

Create a postcss.config.js file in the root of your project and register Tailwind CSS, PostCSS Nesting and Autoprefixer as plugins:

export default {
    plugins: {
        'tailwindcss/nesting': 'postcss-nesting',
        tailwindcss: {},
        autoprefixer: {},
    },
}
export default {
    plugins: {
        'tailwindcss/nesting': 'postcss-nesting',
        tailwindcss: {},
        autoprefixer: {},
    },
}

Automatically refreshing the browser

You may also want to update your vite.config.js file to refresh the page automatically when Livewire components are updated:

import { defineConfig } from 'vite'
import laravel, { refreshPaths } from 'laravel-vite-plugin'
 
export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/css/app.css', 'resources/js/app.js'],
            refresh: [
                ...refreshPaths,
                'app/Livewire/**',
            ],
        }),
    ],
})
import { defineConfig } from 'vite'
import laravel, { refreshPaths } from 'laravel-vite-plugin'

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/css/app.css', 'resources/js/app.js'],
            refresh: [
                ...refreshPaths,
                'app/Livewire/**',
            ],
        }),
    ],
})

Compiling assets

Compile your new CSS and Javascript assets using npm run dev.

Configuring your layout

Create a new resources/views/components/layouts/app.blade.php layout file for Livewire components:

<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
    <head>
        <meta charset="utf-8">
 
        <meta name="application-name" content="{{ config('app.name') }}">
        <meta name="csrf-token" content="{{ csrf_token() }}">
        <meta name="viewport" content="width=device-width, initial-scale=1">
 
        <title>{{ config('app.name') }}</title>
 
        <style>
            [x-cloak] {
                display: none !important;
            }
        </style>
 
        @filamentStyles
        @vite('resources/css/app.css')
    </head>
 
    <body class="antialiased">
        {{ $slot }}
 
        @filamentScripts
        @vite('resources/js/app.js')
    </body>
</html>
<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
    <head>
        <meta charset="utf-8">

        <meta name="application-name" content="{{ config('app.name') }}">
        <meta name="csrf-token" content="{{ csrf_token() }}">
        <meta name="viewport" content="width=device-width, initial-scale=1">

        <title>{{ config('app.name') }}</title>

        <style>
            [x-cloak] {
                display: none !important;
            }
        </style>

        @filamentStyles
        @vite('resources/css/app.css')
    </head>

    <body class="antialiased">
        {{ $slot }}

        @filamentScripts
        @vite('resources/js/app.js')
    </body>
</html>

Publishing configuration

You can publish the package configuration using the following command (optional):

php artisan vendor:publish --tag=filament-config
php artisan vendor:publish --tag=filament-config

Upgrading

Filament automatically upgrades to the latest non-breaking version when you run composer update. After any updates, all Laravel caches need to be cleared, and frontend assets need to be republished. You can do this all at once using the filament:upgrade command, which should have been added to your composer.json file when you ran filament:install the first time:

"post-autoload-dump": [
    // ...
    "@php artisan filament:upgrade"
],
"post-autoload-dump": [
    // ...
    "@php artisan filament:upgrade"
],

Please note that filament:upgrade does not actually handle the update process, as Composer does that already. If you're upgrading manually without a post-autoload-dump hook, you can run the command yourself:

composer update
 
php artisan filament:upgrade
composer update

php artisan filament:upgrade

Edit on GitHub

Still need help? Join our Discord community or open a GitHub discussion

#Requirements

#Installation

#New Laravel projects

#Existing Laravel projects

#Installing Tailwind CSS

#Configuring styles

#Automatically refreshing the browser

#Compiling assets

#Configuring your layout

#Publishing configuration

#Upgrading