Laravel Driver.js

Appearance

Custom Button Handlers ​

By default, Driver.js handles button clicks automatically: "Next" moves to the next step, "Previous" goes back, and "Close" destroys the tour. However, you can override this behavior with custom handlers.

Available Button Hooks ​

MethodDefault Behavior (if not overridden)
onNextClick($callback)Move to next step
onPrevClick($callback)Move to previous step
onCloseClick($callback)Destroy the driver

Method Signatures ​

php
DriverJs::onNextClick(string $callback);
DriverJs::onPrevClick(string $callback);
DriverJs::onCloseClick(string $callback);

Parameters ​

  • $callback (string): The name of a JavaScript function or inline JavaScript expression.

Example: Custom Next Click Handler ​

php
use RealRashid\LaravelDriverJs\Facades\DriverJs;

DriverJs::tour('onboarding')
    ->onNextClick('customNextHandler')
    ->step('#header', 'Welcome')
    ->step('#nav', 'Navigation')
    ->render();
javascript
// In your JavaScript
function customNextHandler(element, step, opts) {
    // Perform some custom logic before moving to the next step
    console.log('Moving to next step from:', element);

    // You must manually move to the next step
    opts.driver.moveNext();
}

Example: Async Next Click Handler ​

A powerful pattern is dynamically loading steps based on user interaction:

php
DriverJs::tour('dynamic-tour')
    ->onNextClick('dynamicNextHandler')
    ->step('#header', 'Welcome', 'Let us show you around.')
    ->render();
javascript
// In your JavaScript
async function dynamicNextHandler(element, step, opts) {
    // Fetch new steps from the server
    const response = await fetch('/api/tour/next-steps');
    const steps = await response.json();

    // Update the driver with new steps
    opts.driver.setSteps(steps);
    opts.driver.moveNext();
}

Example: Custom Close Handler ​

php
DriverJs::tour('onboarding')
    ->onCloseClick('customCloseHandler')
    ->step('#header', 'Welcome')
    ->render();
javascript
// In your JavaScript
function customCloseHandler(element, step, opts) {
    // Log analytics before closing
    analytics.track('tour_closed_prematurely', {
        step: opts.state.activeIndex,
        total: opts.config.steps.length
    });

    // Actually destroy the tour
    opts.driver.destroy();
}

Step-Level Button Hooks ​

You can also override button behavior on individual steps using the step builder methods:

php
DriverJs::addStep('#header')
    ->title('Welcome')
    ->description('The main header.')
    ->popoverClass('welcome-step')
    ->onNextClick('welcomeNextHandler')
    ->onPrevClick('welcomePrevHandler')
    ->onCloseClick('welcomeCloseHandler');

If you prefer addSteps(), the equivalent array keys are on_next_click, on_prev_click, on_close_click, and on_popover_render.

Important Notes ​

  • When you override a button click handler, the default behavior is completely replaced. You must manually call the appropriate driver method (e.g., opts.driver.moveNext()) if you still want the default navigation to occur.
  • The callback receives three arguments: element (the DOM element), step (the step configuration), and opts (an object containing config, state, and driver).
  • The opts.driver reference allows you to call any Driver.js method from within your callback.

That's it! You're now equipped to create custom button handlers using Laravel Driver.js.