Switch plugin

Activitylog Pro Auto Translator Media Library Manager Notifications Pro Onboarding Manager Pro Pulse Record Finder Pro Upload Pro

Getting started

Installation Upgrade guide

Usage

Defining tracks & steps Preventing dashboard access Advanced example

Preventing dashboard access

The package also provides easy functionality to prevent the users from accessing the dashboard. In order to force a user to complete a track, you can chain the ->completeBeforeAccess() to the track:

php

Track::make([
    Step::make(name: 'Connect Notion', identifier: 'widget::connect-notion')
        ->description('Sign in with Notion and grant access to your workspace.')
        ->icon('heroicon-o-check-circle')
        ->performStepActionLabel('Add workspace →')
        ->url(route('callbacks.notion.authorize'))
        ->completeIf(fn () => auth()->user()->workspaces()->exists())
        ->columnSpan(1),
    // Other steps
    // Step::make(/** */)...
    // Step::make(/** */)...
])
->completeBeforeAccess()

Next, you should register a middleware. Open your panel service providers and add the middleware to the ->authMiddleware() or ->tenantMiddleware(). If you are using a panel without tenancy, you should use the ->authMiddleware() method. If you are using a panel with tenancy, you should use the ->tenantMiddleware() method. In both methods, you should add the OnboardMiddleware::class to the end of the array.

app/Providers/Filament/YourPanelProvider.php

use RalphJSmit\Filament\Onboard\Http\Middleware\OnboardMiddleware;

$panel
    // If you have a panel without tenancy:
    ->authMiddleware([
        Authenticate::class,
        OnboardMiddleware::class, // Add here.
    ])
    // Or, if you have a panel with tenancy:
    ->tenantMiddleware([
        OnboardMiddleware::class, // Add here.
    ])

Now, whenever a user visits a page and there is still a track with uncompleted steps, they will be automatically redirected to a page where they can complete that step.

Allowing routes to be always accessible

If you would like to whitelist certain pages that should be accessible at all times to users, without the middleware kicking in to redirect the user to the onboarding page, you can provide the route in $plugin->accessibleRoutes() to whitelist the page:

php

$plugin
    ->accessibleRoutes([
        'filament.app.pages.dashboard',
        'filament.app.pages.profile',
    ])

Exact route names can be determined by running php artisan route:list in your terminal.

Custom url when completing before access

By default, this page will have the url path "/filament/onboard". You can change this url by providing a different prefix to the ->prefix() method when configuring the plugin:

php

$plugin
    // This is the route prefix that will be used for the route(s) in the package.
    // Currently, there is only one route, but this prefix would also be used for
    // new routes if new routes would ever be added.
    ->prefix('welcome')

Forcing a user to visit a link

If you want your users to visit a url, e.g. for an OAuth app, you can use the exact same syntax as described earlier, without any changes.

Adding wizards

If you want your user to complete a wizard, you can use the ->wizard(/** Your wizard steps */) method:

php

use Filament\Forms\Components\TextInput;
use Filament\Forms\Components\Wizard\Step as WizardStep;
use RalphJSmit\Filament\Onboard\Step;

Step::make('Your title', 'onboard::unique-identifier')
    ->wizard([
        WizardStep::make("Your label")
            ->statePath('step_1') // It is recommended to keep the form data in a separate array key for each step. 
            ->schema([
                TextInput::make('name')
                    ->required(),
                Select::make('plan_id')
                    ->options([
                        'default' => 'Regular',
                        'pro' => 'Pro',
                        'unlimited' => 'Unlimited'
                    ])
                    ->required(),
                // More components...
            ])    
            // More steps...
    ])

NB. The example imports the steps for the wizard using Filament\Forms\Components\Wizard\Step as WizardStep. Otherwise, it would collide with the RalphJSmit\Filament\Onboard\Step. The actual class name is still Step.

For all the Step configuration options (adding an icon and description), see the Filament documentation.

Pre-filling the wizard form with data

You can use the ->wizardFillFormUsing() method to specify data that will be pre-filled into the form. For example, this is useful if you want to retrieve information about an existing record.

php

use Filament\Forms\Components\Wizard\Step as WizardStep;
use RalphJSmit\Filament\Onboard\Step;

Step::make('Your title', 'onboard::unique-identifier')
    ->wizard([
        WizardStep::make("Your label")
            ->statePath('step_1') // It is recommended to keep the form data separate for each step.
            ->schema([
                TextInput::make('name')
                    ->required(),
                // ...
            ])
            // ...
    ]) 
    ->wizardFillFormUsing(function() {
        return [
            'step_1' => [
                'name' => auth()->user()->name,
                // ...
            ],
            'step_2' => [
                // ...
            ]
        ];
    })

Saving the data on form submit

You can use the ->wizardSubmitFormUsing() method to pass a closure that will be executed when a user submits a form. The closure receives two parameters:

Parameter	Description
`array $state`	An array of the submitted form data. The data is already validated.
`\RalphJSmit\Filament\Onboard\Http\Livewire\Wizard $livewire`	The Livewire component that is used to render the wizard.

You can omit one of the parameters if you don't need it, but make sure to always use the parameter names $state and $livewire. Dependency injection is also supported.

Usually you will use this closure to save the data and then redirect. It is handy to redirect the user to the panel's home page using filament()->getPanel()->getUrl(), because if there are no steps left, the user will be redirected to the dashboard. And if there still are steps to complete, the middleware will automatically pick that up and redirect the user to the next step.

php

use Filament\Forms\Components\Wizard\Step as WizardStep;
use RalphJSmit\Filament\Onboard\Step;

Step::make('Your title', 'onboard::unique-identifier')
    ->wizard([
        WizardStep::make("Your label")
            ->statePath('step_1') // It is recommended to keep the form data separate for each step.
            ->schema([
                TextInput::make('name')
                    ->required(),
                // ...
            ])
            // ...
    ])
    ->wizardFillFormUsing(function() {
        // ...
    })
    ->wizardSubmitFormUsing(function(array $state, \RalphJSmit\Filament\Onboard\Http\Livewire\Wizard $livewire) {
        auth()->user()->update($state['step_1']);
        // ...
        
        $livewire->redirect(filament()->getPanel()->getUrl());
    })

Customizing the Wizard "submit" button

You can customize the "submit" button in the wizard by using the ->wizardSubmitButton("Your label") method.

Marking the wizard as completed

Don't forget to use the ->completeIf() method to specify when the wizard step has been completed. Otherwise, your users might be locked into the wizard forever.

php

->completeIf(fn () => user()->plan_id !== null)

Customizing the wizard

You can customize the wizard using the ->modifyWizardUsing() function:

php

->modifyWizardUsing(function (\Filament\Forms\Components\Wizard $wizard) {
    return $wizard->nextAction(fn (StaticAction $action) => $action->icon('heroicon-m-arrow-right'));
})

Changing the card width

You can use the ->cardWidth() method to specify how wide the link or wizard should be rendered.

Possible values are: xs, sm, md, lg, xl, 2xl, 3xl, 4xl, 5xl, 6xl, 7xl.

Customizing the redirect

By default, the package redirects the user to the admin dashboard after successfully completing the onboarding flow. However, you may customize the route that it uses using the $plugin->redirectRoute().

Make sure to add a route and not a url. Inputting a url won't work, only routes do.

php

$plugin
    ->redirectRoute('some-custom-route')

On this page

✦Available to AI agents

Read this page inside your coding agent – run the skill via Laravel Boost:

Filament Plugins

Preventing dashboard access