You built the admin in Filament, it took a week, and it is excellent. Then the brief lands: customers need to manage their own orders. Same validation, same columns, same confirmation dialogs — but on your marketing layout, with your navigation, nowhere near /admin. The two obvious options are both bad. Rebuild it in plain Livewire and you now maintain two definitions of the same form forever. Bend a panel into looking like your front end and you fight it on every minor release.
There is a third option, and it is the one Filament was designed for. The panel is not Filament. The panel is a consumer of Filament.
What you'll learn#
- How Filament v5 is packaged, and which packages you actually need without a panel
- How to render a schema, a table and an action inside an ordinary Livewire component
- How to share one form definition between an admin resource and a customer-facing page
- How to load Filament's CSS and JS in your own layout without breaking your design system
- Where authorization silently stops happening, and the checklist that closes the gap
- How to test all of it with Pest
How Filament v5 is actually packaged#
Filament is a monorepo that publishes several standalone Composer packages. filament/support carries the Blade components, colours, icons and the asset manager. filament/schemas provides the Schema object and the layout components. filament/forms and filament/infolists provide the input and display components that live inside a schema. filament/tables provides the table builder. filament/actions provides actions and their modals. filament/notifications provides the flash notification system. filament/widgets provides stats and charts.
filament/filament — the panel builder — depends on all of these and glues them together with routing, navigation, authentication, tenancy and resource classes. That glue is genuinely useful when you want an admin panel. It is actively unhelpful when you want a customer portal, because it owns the layout, the URL prefix and the auth guard.
The packages also depend on each other in one direction. Installing filament/tables brings in filament/actions, filament/forms, filament/schemas and filament/support. Installing filament/forms brings in filament/actions, filament/schemas and filament/support. So in practice you require the top-level thing you want and let Composer resolve the rest.
What you lose by dropping the panel is real and worth naming up front: no automatic routing, no navigation, no breadcrumbs, no global search, no tenancy scoping, and — the big one — no automatic policy enforcement. Resource classes are where Filament calls viewAny(), update() and friends. Outside a resource, nothing calls them. We come back to that.
If you are still on v4, the packaging is broadly the same but the namespaces moved: Filament\Forms\Form became Filament\Schemas\Schema, and form definitions now live in schema() rather than form() in several places. The step-by-step v4 to v5 migration guide covers the rename in full, and it is worth doing before you start sharing definitions across contexts.
Install only the packages you need#
For a customer order portal with a form, a table and an action, filament/tables and filament/notifications cover everything:
composer require filament/tables:"^5.0" filament/notifications:"^5.0"
php artisan filament:install
filament:install publishes the frontend assets without scaffolding over your existing layout. Do not pass --scaffold on an existing application — it overwrites files.
Then import the CSS for exactly the packages you installed, in resources/css/app.css:
@import 'tailwindcss';
/* Required by all components */
@import '../../vendor/filament/support/resources/css/index.css';
/* Required by actions and tables */
@import '../../vendor/filament/actions/resources/css/index.css';
/* Required by actions, forms and tables */
@import '../../vendor/filament/forms/resources/css/index.css';
/* Required by actions, infolists, forms, schemas and tables */
@import '../../vendor/filament/schemas/resources/css/index.css';
/* Required by tables */
@import '../../vendor/filament/tables/resources/css/index.css';
/* Required by notifications */
@import '../../vendor/filament/notifications/resources/css/index.css';
@variant dark (&:where(.dark, .dark *));
That last line matters more than it looks. Filament's components are written against a dark variant that resolves to a .dark class on an ancestor element, not the prefers-color-scheme media query that Tailwind v4 uses by default. If your own site drives dark mode from the media query, Filament's components will be stuck in light mode inside a dark page. Defining a custom dark variant in Tailwind v4 is how you reconcile the two — pick the class strategy for both, and toggle .dark on <html> yourself.
Build a standalone form page#
A Livewire component becomes a Filament form host by doing five things: implement HasSchemas, use InteractsWithSchemas, hold the state in a public property, define a schema method that points at that property with statePath(), and call fill() in mount(). Miss the fill() call and the form renders empty and throws on submit, even when there is no initial data.
<?php
namespace App\Livewire\Portal;
use App\Filament\Schemas\OrderForm;
use App\Models\Order;
use Filament\Notifications\Notification;
use Filament\Schemas\Concerns\InteractsWithSchemas;
use Filament\Schemas\Concerns\RestrictsFileUploadsToSchemaComponents;
use Filament\Schemas\Contracts\HasSchemas;
use Filament\Schemas\Schema;
use Illuminate\Contracts\View\View;
use Illuminate\Support\Facades\Gate;
use Livewire\Attributes\Locked;
use Livewire\Component;
class EditOrder extends Component implements HasSchemas
{
use InteractsWithSchemas;
use RestrictsFileUploadsToSchemaComponents;
#[Locked]
public int $orderId;
public ?array $data = [];
public function mount(Order $order): void
{
Gate::authorize('update', $order);
$this->orderId = $order->getKey();
$this->form->fill($order->attributesToArray());
}
public function form(Schema $schema): Schema
{
return OrderForm::configure($schema)
->statePath('data')
->model($this->order());
}
public function save(): void
{
$order = $this->order();
$order->update($this->form->getState());
Notification::make()
->title('Order updated')
->success()
->send();
}
protected function order(): Order
{
$order = Order::query()
->whereBelongsTo(auth()->user()->customer)
->findOrFail($this->orderId);
Gate::authorize('update', $order);
return $order;
}
public function render(): View
{
return view('livewire.portal.edit-order')
->layout('layouts.portal');
}
}
Two details are doing real work here. #[Locked] plus a scalar ID, rather than a public Order $order property, is the pattern Filament's own security documentation recommends: Livewire restores model properties from the snapshot with an unscoped query on every subsequent request, so a model that was authorised at mount is not re-authorised later. Re-querying through the relationship on each use closes that. And RestrictsFileUploadsToSchemaComponents is new in v5 — InteractsWithSchemas composes Livewire's WithFileUploads, which means every page using it exposes upload RPC methods for arbitrary property paths unless you add that trait.
The view is unremarkable, which is the point:
<div>
<form wire:submit="save" class="space-y-6">
{{ $this->form }}
<x-filament::button type="submit">
Save changes
</x-filament::button>
</form>
<x-filament-actions::modals />
</div>
<x-filament-actions::modals /> renders the modal markup for any action inside the schema. It must sit outside the <form> element but inside the Livewire root, and it is only needed once per component. Forgetting it produces the single most common bug report on this pattern: buttons that visibly do nothing.
If your portal form is simple enough that it needs no Filament components at all, do not reach for this — Livewire 4 form objects with #[Validate] are lighter and will serve you better.
Share one schema between the panel and the portal#
Defining the fields inline in the Livewire component would leave you exactly where you started: two copies drifting apart. Extract the definition into its own class with a static configure() method, which is the same convention Filament v5 uses for resource schemas.
<?php
namespace App\Filament\Schemas;
use App\Enums\OrderStatus;
use Filament\Forms\Components\DatePicker;
use Filament\Forms\Components\Select;
use Filament\Forms\Components\Textarea;
use Filament\Forms\Components\TextInput;
use Filament\Schemas\Components\Section;
use Filament\Schemas\Schema;
class OrderForm
{
public static function configure(Schema $schema, bool $isStaff = false): Schema
{
return $schema->components([
Section::make('Delivery')
->schema([
TextInput::make('recipient_name')
->required()
->maxLength(120),
Textarea::make('delivery_notes')
->rows(3)
->maxLength(500),
DatePicker::make('requested_for')
->native(false)
->minDate(today()),
]),
Section::make('Fulfilment')
->visible($isStaff)
->schema([
Select::make('status')
->options(OrderStatus::class)
->required(),
TextInput::make('internal_reference'),
]),
]);
}
}
The panel resource calls it with $isStaff: true; the portal page calls it with the default. Resist the temptation to branch on auth()->user()->isStaff() inside the schema — an explicit parameter keeps the definition honest about what varies, and makes it testable without logging anyone in.
A warning that is easy to miss: visible(false) hides a field from the UI, it does not reject the value. A customer can still submit status in the Livewire payload. The field-level fix is to mark staff-only fields ->dehydrated(false) for non-staff, but the real fix is to not trust getState() wholesale on write — see the authorization section below.
Build a standalone table scoped to the customer#
Tables need three interfaces and three traits, because a table hosts actions, and actions host schemas:
<?php
namespace App\Livewire\Portal;
use App\Models\Order;
use Filament\Actions\Concerns\InteractsWithActions;
use Filament\Actions\Contracts\HasActions;
use Filament\Schemas\Concerns\InteractsWithSchemas;
use Filament\Schemas\Concerns\RestrictsFileUploadsToSchemaComponents;
use Filament\Schemas\Contracts\HasSchemas;
use Filament\Tables\Columns\TextColumn;
use Filament\Tables\Concerns\InteractsWithTable;
use Filament\Tables\Contracts\HasTable;
use Filament\Tables\Filters\SelectFilter;
use Filament\Tables\Filters\TernaryFilter;
use Filament\Tables\Table;
use Illuminate\Contracts\View\View;
use Illuminate\Database\Eloquent\Builder;
use Livewire\Component;
class OrderList extends Component implements HasActions, HasSchemas, HasTable
{
use InteractsWithActions;
use InteractsWithSchemas;
use InteractsWithTable;
use RestrictsFileUploadsToSchemaComponents;
public function table(Table $table): Table
{
return $table
->query(fn (): Builder => Order::query()
->whereBelongsTo(auth()->user()->customer))
->columns([
TextColumn::make('reference')
->searchable()
->sortable(),
TextColumn::make('status')
->badge(),
TextColumn::make('total')
->money('gbp')
->sortable(),
TextColumn::make('requested_for')
->date('j M Y')
->sortable(),
])
->filters([
SelectFilter::make('status')
->options(OrderStatus::class),
TernaryFilter::make('requested_for')
->label('Scheduled')
->nullable(),
])
->recordActions([
$this->cancelOrderAction(),
])
->defaultSort('requested_for', 'desc')
->deferLoading();
}
public function render(): View
{
return view('livewire.portal.order-list')->layout('layouts.portal');
}
}
The query() closure is the only thing standing between this customer and every other customer's orders. There is no tenancy scope, no resource getEloquentQuery(), no panel middleware. Pass a closure rather than a resolved builder so the scoping is re-evaluated on every request rather than captured once in the component snapshot.
deferLoading() is worth adding on a public page: the first paint renders the table chrome and a loading state, and the query runs in a follow-up request. On a portal where the rest of the page is static marketing-grade HTML, that is the difference between a fast-feeling page and one that waits on a join. If your table is genuinely large, the techniques in tuning Filament v5 tables for large datasets apply unchanged outside a panel.
Filters, sorting, search and pagination all keep working. What you lose is the panel's URL state integration for filters — if you want those in the query string, wire them yourself with Livewire's #[Url] attribute for query string filters.
Render an action anywhere#
Actions are the piece that feels least likely to work outside a panel, and in practice they are the smoothest. An action is a method on the component returning an Action, named either exactly after the action or with an Action suffix.
use App\Models\Order;
use Filament\Actions\Action;
use Filament\Forms\Components\Textarea;
use Filament\Notifications\Notification;
use Illuminate\Support\Facades\Gate;
public function cancelOrderAction(): Action
{
return Action::make('cancelOrder')
->label('Cancel order')
->color('danger')
->icon('heroicon-m-x-circle')
->requiresConfirmation()
->modalHeading('Cancel this order?')
->modalDescription('We will email you a confirmation. This cannot be undone.')
->schema([
Textarea::make('reason')
->label('Why are you cancelling?')
->required()
->maxLength(500),
])
->visible(fn (Order $record): bool => Gate::allows('cancel', $record))
->action(function (Order $record, array $data): void {
Gate::authorize('cancel', $record);
$record->cancel($data['reason']);
Notification::make()
->title('Order cancelled')
->body("Order {$record->reference} has been cancelled.")
->success()
->send();
});
}
Note that visible() and the Gate::authorize() inside action() are both present, and both are necessary. visible() controls what the user sees; the check inside action() is what actually stops the request. Filament's own documentation is explicit that custom actions are not authorised automatically.
To render that action outside a table — in a Blade view that is otherwise nothing to do with Filament:
<article class="prose">
<h1>{{ $order->reference }}</h1>
@if ($this->cancelOrderAction->isVisible())
{{ $this->cancelOrderAction }}
@endif
<x-filament-actions::modals />
</article>
The isVisible() guard matters because {{ $this->cancelOrderAction }} renders a disabled button rather than nothing when the action is hidden. The patterns in building custom action confirmations and notifications carry over directly; only the host changes.
For the notification to actually appear, your layout needs @livewire('notifications') — covered next.
Get the assets and layout right#
This is where most attempts fail, and the failure mode is confusing: the markup is there, the classes are there, and nothing is styled. Three directives, in three specific places:
<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}" class="antialiased">
<head>
<meta charset="utf-8">
<meta name="csrf-token" content="{{ csrf_token() }}">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{{ $title ?? config('app.name') }}</title>
<style>[x-cloak] { display: none !important; }</style>
@filamentStyles
@vite('resources/css/app.css')
</head>
<body class="bg-white dark:bg-gray-950">
<x-portal.navigation />
<main class="mx-auto max-w-5xl px-4 py-10">
{{ $slot }}
</main>
@livewire('notifications')
@filamentScripts
@vite('resources/js/app.js')
</body>
</html>
The ordering is not stylistic. @filamentStyles goes before @vite('resources/css/app.css') so that your own stylesheet wins specificity ties rather than losing them. @filamentScripts goes at the end of the body and must come before your own app.js if that file also boots Alpine — @filamentScripts registers Alpine along with Filament's plugins, and a second Alpine.start() throws "Alpine has already been initialized". If you are on the Laravel starter kits, delete the Alpine.start() from resources/js/app.js and let Filament own it.
[x-cloak] is not decoration either. Without it you get a flash of every dropdown and modal in the page on first paint.
One more trap specific to portals: if your navigation uses wire:navigate, Filament's scripts are loaded once and persist across navigations, which is fine — but any @pushed inline script in a page view will not re-run. Keep page-specific JavaScript inside Alpine component definitions rather than inline scripts, as covered in using wire:navigate for an SPA feel.
Theme Filament against your own design system#
There are two honest strategies and they do not mix well.
Strategy one: let Filament keep its own look. Import Filament's CSS as shown earlier and treat its components as a visually distinct island inside your page — a styled card containing a form. This takes about ten minutes, survives upgrades without thought, and is the right answer for an internal-ish portal or an onboarding wizard where nobody is grading the pixels.
Strategy two: extend your token set into Filament's theme. Filament v5 reads its palette from CSS custom properties generated by FilamentColor::register(), so you can point it at the same OKLCH tokens your design system already uses:
// app/Providers/AppServiceProvider.php
use Filament\Support\Colors\Color;
use Filament\Support\Facades\FilamentColor;
public function boot(): void
{
FilamentColor::register([
'primary' => Color::hex('#0f766e'),
'danger' => Color::hex('#b91c1c'),
'gray' => Color::Slate,
]);
}
Then override the handful of structural things in your own stylesheet, loaded after Filament's:
@layer components {
.fi-input-wrp {
border-radius: var(--radius-lg);
}
.fi-btn {
font-family: var(--font-display);
letter-spacing: -0.01em;
}
}
Those fi-* class names are Filament's documented CSS hooks and are treated as public API, which is the critical difference between this and the approach most people reach for first — writing deep descendant selectors with !important against whatever classes the inspector shows. Those break on patch releases. The hooks do not.
What does not work is expecting your global input, button or .prose styles to apply inside Filament components. They are utility-classed from the inside out and will win. If you have an established component library, the thinking in white-labelling a Filament theme applies here too, minus the panel registration step.
Authorization: nothing is checking for you#
This is the section to read twice. Inside a panel, a resource calls your model policy for viewAny, view, create, update and delete. Outside a panel, none of that happens. There is no resource, so there is no caller. A policy class that you wrote and tested will sit there, never invoked, while your portal cheerfully serves every row in the table.
There are four places a gate belongs, and all four need to be filled:
The query. Scope it to the authenticated user in table()->query() and in any findOrFail(). This is the only layer that prevents data leaking into a list.
The action. Use visible() or authorize() for the UI, and a Gate::authorize() call inside action() for the request. Action arguments are client-controlled, so if you pass a record ID as an argument, re-query and re-authorize it rather than trusting it.
The form's write path. $this->form->getState() returns everything the schema dehydrated, including fields a tampered request added. Either mark privileged fields ->dehydrated(false) when the user is not staff, or — better — pick the keys you accept explicitly on the write:
$order->update(
collect($this->form->getState())
->only(['recipient_name', 'delivery_notes', 'requested_for'])
->all()
);
The restored model. Covered above: store a locked scalar ID, re-query through the ownership relationship, re-authorize. Livewire's own model restoration does not reapply global scopes.
A fifth thing worth saying plainly: tenancy does not come with you. Filament registers its tenant global scope when a tenant-aware panel identifies the current tenant. Your portal route never does, so queries that were implicitly scoped inside a multi-tenant team panel are completely unscoped here. If you are reusing models from a tenant-aware panel, assume every query needs an explicit where.
If you want the full picture of the layer this replaces, Filament v5 authorization with policies, roles and permissions documents what the panel does for you — read it as a specification of what you now have to do by hand.
Testing this#
The components are plain Livewire components, so Filament's Pest helpers work on them exactly as they do on resource pages. Three tests cover the three surfaces.
use App\Livewire\Portal\EditOrder;
use App\Livewire\Portal\OrderList;
use App\Models\Customer;
use App\Models\Order;
use App\Models\User;
use Filament\Actions\Testing\TestAction;
use function Pest\Livewire\livewire;
it('saves the portal order form', function () {
$customer = Customer::factory()->hasUsers(1)->create();
$order = Order::factory()->for($customer)->create();
$this->actingAs($customer->users->first());
livewire(EditOrder::class, ['order' => $order])
->fillForm([
'recipient_name' => 'Ada Lovelace',
'delivery_notes' => 'Leave with the concierge.',
])
->call('save')
->assertHasNoFormErrors();
expect($order->refresh()->recipient_name)->toBe('Ada Lovelace');
});
it('only lists the authenticated customer orders', function () {
$mine = Order::factory()->count(2)->create();
$theirs = Order::factory()->count(3)->create();
$this->actingAs($mine->first()->customer->users()->first());
livewire(OrderList::class)
->assertCanSeeTableRecords($mine)
->assertCanNotSeeTableRecords($theirs);
});
it('refuses to cancel an order the user does not own', function () {
$order = Order::factory()->create();
$this->actingAs(User::factory()->create());
livewire(OrderList::class)
->assertActionHidden(
TestAction::make('cancelOrder')->table($order),
);
});
The third test is the one that earns its keep. Delete the whereBelongsTo() from table()->query() and it fails — which is exactly the regression you are most likely to introduce six months from now when someone "simplifies" the query. Write the negative authorization test before the happy path. The helper vocabulary is identical to testing Filament v5 resources with Pest, and the component-level patterns in testing Livewire 4 components with Pest fill in the rest.
Common mistakes#
Installing filament/filament by accident. composer require filament/filament pulls the whole panel builder, registers routes at /admin and adds a panel provider. If you only need components, require the component packages.
Forgetting <x-filament-actions::modals />. Action buttons render, clicks register, nothing opens. One occurrence per Livewire component, outside the <form>.
Forgetting $this->form->fill() in mount(). Required even with no initial data. The error it produces when missing does not mention fill().
Assuming Tailwind will generate classes it cannot see. Filament's CSS is pre-built, but if you add your own utility classes inside Filament component configuration — extraAttributes(['class' => 'rounded-3xl']) — Tailwind needs those files in its @source paths or the class is never generated.
Two copies of Alpine. @filamentScripts boots Alpine. If resources/js/app.js calls Alpine.start() too, everything Alpine-driven silently dies.
Assuming policies fire. They do not. Covered at length above, and it is the mistake with the highest cost.
Assuming tenancy scoping applies. It does not. Every query is unscoped unless you scope it.
When not to do this#
If the page is genuinely internal — operations staff, support agents, anyone who already logs in to do their job — just make a panel. A second Filament panel takes an afternoon, gives you auth, navigation, policies and tenancy for free, and can be branded well enough that nobody complains. The standalone route costs you all of that in exchange for layout control you probably do not need.
Equally, if you want a Filament-shaped page with some custom content on it, you want a custom Filament page hosting Livewire widgets, not this. The standalone packages are for when the surrounding page is emphatically not Filament: a marketing-styled portal, an embedded widget on a public site, a multi-step signup that has to match the brand exactly.
The honest test is whether you would be happy for the page to look like an admin panel. If the answer is yes, build a panel.
Wrapping up#
We built a customer order portal that reuses the exact schema definition from the admin resource, renders a scoped table with filters, and exposes a confirmation action with a modal form and a success notification — all on your own layout, with your own navigation, and no panel anywhere near it. The moving parts are: the right packages, the HasSchemas/HasTable/HasActions triad, three asset directives in the right order, and a deliberate authorization layer to replace the one the panel was providing.
Three things to do next. Write the negative authorization test first — the one that fails when the query scope is removed. Then read Filament v5 authorization with policies, roles and permissions as a checklist of what you are now responsible for. And if you are still on v4, do the upgrade before you start sharing schema definitions between contexts — the namespace moves are much more painful to untangle once two consumers depend on one class.
FAQ#
Can I use Filament forms without a panel?
Yes. filament/forms and filament/schemas are standalone Composer packages and work in any Livewire component that implements HasSchemas and uses the InteractsWithSchemas trait. You define a form(Schema $schema): Schema method, point it at a public property with statePath(), call $this->form->fill() in mount(), and render it with {{ $this->form }}. The panel builder is a consumer of these packages, not a prerequisite for them.
How do I add a Filament table to a custom Livewire component?
Implement the HasTable, HasActions and HasSchemas interfaces, use the InteractsWithTable, InteractsWithActions and InteractsWithSchemas traits, and add a table(Table $table): Table method that defines the base query, columns, filters and actions. Render it in your Blade view with {{ $this->table }}. You need all three interfaces because a table can host actions, and actions can host schemas.
Can I use Filament on a public-facing page?
Yes, and the components themselves are fine on an unauthenticated page. Two cautions apply. Add the RestrictsFileUploadsToSchemaComponents trait, because InteractsWithSchemas exposes Livewire's upload RPC methods on any page that uses it. And treat every query and every action as unauthorised by default — there is no panel middleware and no resource policy enforcement to fall back on.
Do I need a Filament licence to use the open-source packages?
No. The core Filament packages — support, schemas, forms, infolists, tables, actions, notifications and widgets — are MIT licensed and free to use commercially, with or without a panel. Paid licences apply only to specific commercial plugins and themes sold through the Filament store, not to the framework packages described in this guide.
How do I load Filament's CSS and JS in my own layout?
Put @filamentStyles in the <head> before your own @vite stylesheet, and @filamentScripts at the end of the <body> before your own app.js. Import the per-package CSS files from vendor/filament/*/resources/css/index.css into your resources/css/app.css, and add @variant dark (&:where(.dark, .dark *)); so Filament's dark mode uses a class rather than the media query. If you want flash notifications, add @livewire('notifications') to the layout too.
How do I handle authorization outside a panel?
Manually, in four places: scope the table and lookup queries to the authenticated user, gate the action with both visible() and a Gate::authorize() call inside action(), restrict which form keys you accept on write rather than trusting getState() wholesale, and store a locked scalar ID instead of a model property so the record is re-queried and re-authorised on every request. Model policies are never called automatically without a resource class to call them.
Why are my Filament components unstyled on a non-panel page?
Almost always one of three things. @filamentStyles is missing from the layout head; the per-package CSS imports are missing from resources/css/app.css; or your own stylesheet loads before Filament's and loses the specificity battle. If only some components look wrong, check whether custom utility classes you passed through extraAttributes() are inside Tailwind's @source paths — Filament's own CSS is pre-built, but your additions are not.
Can I share the same form definition between a Filament resource and a custom page?
Yes, and you should. Extract the field definitions into a plain class with a static configure(Schema $schema): Schema method, then call it from both the resource's schema method and the Livewire component's form() method. Pass explicit parameters for anything that varies by context — a bool $isStaff flag beats branching on auth()->user() inside the schema, because it keeps the definition testable and makes the variation visible at the call site.