Toggle Laravel Package

Getting Started

Install the package into a Laravel app that already runs Laravel Nova 3 (this field is Nova‑3 only):

composer require naif/toggle

No service provider registration is required in config/app.php; the field is resolved by class, and Nova autoloads the field's Vue component. If you are running Nova in production, run php artisan nova:publish once after install so the compiled toggle asset is copied into public/vendor/nova.

First use case — a boolean flag on an Eloquent model (e.g. publishing state):

1. Add a boolean column in a migration:

$table->boolean('is_active')->default(false);

2. Cast it on the model so it hydrates as true/false:

protected $casts = ['is_active' => 'boolean'];

3. Register the field on the resource:

use Naif\Toggle\Toggle;

public function fields(Request $request)
{
    return [
        Toggle::make('Is Active'),
    ];
}

Where to look first in the repo github.com/naifalshaye/toggle-switch: the src/ directory contains a single field class (usually Toggle.php) extending Laravel\Nova\Fields\Field. That class is where you see $component, the default resolve/fill behaviour, and any custom macros. resources/js/ (or dist/) holds the Vue toggle component — the fastest way to understand what the field renders is to read the Vue component's props and modelValue handling. The README is short; treat the field class as the source of truth for available methods.

Implementation Patterns

Basic boolean field. The canonical pattern is a Toggle::make('flag') mapped to a boolean DB column with a model cast. Without the cast, Nova will hydrate the raw 0/1 and the toggle's modelValue may render inconsistently between index and detail views.

Index vs. detail. Nova renders the same field component in both contexts. A typical pattern is to keep the toggle editable on forms but read-only on the index, so accidental row-level changes are avoided:

Toggle::make('Is Active')
    ->readonly(fn () => request()->routeIs('nova.resources.index')),

Or use Nova's standard ->onlyOnForms() / ->onlyOnDetail() helpers if your version of the field inherits them correctly (they are inherited from Field, so they work).

Dependent fields. Because it is a normal field, it composes with Nova's dependency API. A common workflow is to reveal a "publish date" only when the toggle is on:

Toggle::make('Scheduled'),
DateTime::make('Publish At')
    ->dependsOn('Scheduled', true),

The dependency resolves against the field's underlying value, so remember that the Eloquent cast matters: if the model returns 1 instead of true, the dependsOn comparison needs to match the value the DB actually returns.

Filters and sorting. Pair the field with a Nova boolean filter for list views:

public function filters(Request $request)
{
    return [new ActiveFilter];
}

Sorting booleans is database‑specific (MySQL sorts 0 before 1; Postgres may need an expression). If ->sortable() is exposed by the field, verify the column's type before enabling it — otherwise leave sorting off and put the toggle in a filter instead.

Actions and bulk toggles. For "activate all selected" workflows, drive the state through a Nova Action rather than expecting single-click index toggling. The field persists through the normal fill() on save, so mass updates via actions are safer than relying on inline index behaviour if the component is not wired for optimistic updates.

Authorization and visibility. Use Nova's inherited helpers instead of custom logic:

Toggle::make('Is Active')
    ->canSee(fn () => $this->user()->can('publish', $this->resource))
    ->hideWhenCreating()
    ->hideWhenUpdating(fn () => $this->resource->published_at !== null),

Defaults on create. Since boolean columns default to 0, set a sensible initial value so the toggle does not show as "off" for records where the user expects "on":

Toggle::make('Is Active')->default(true)

Verify this against the field's resolveUsing behaviour — some packages treat default() as a form-only default while others inject it into the model on resolve.

Gotchas and Tips

Nova 4/5 incompatibility. The last release is September 2021 and the field targets Nova 3. If you upgrade Nova to 4+, the field's Vue component and $component reference will break, and Nova 4's field API has moved to a different asset and bootstrapping model. Pin Nova 3 alongside this package or budget time to fork and rewrite the component.

Boolean false is not "empty". A classic Nova pitfall: required on a boolean toggle rejects a legitimate false value because Laravel's required rule treats false as empty. Use ->rules('boolean') or Rule::in([true, false]) instead of required, and ensure the column is boolean/tinyint(1) not nullable, or false will round-trip to null and the toggle resets on the next save.

Cast the model attribute. Without protected $casts = ['flag' => 'boolean'], the field often appears to "work on save but shows the wrong state on next load" because the DB returns 0/1. This is the number one reason a toggle looks stuck.

Publish assets after composer updates. After composer require or composer update, run php artisan nova:publish (and php artisan view:clear) — Nova caches the manifests of registered fields, and a stale manifest produces a blank or console-erroring field. Debugging a blank field usually means checking the browser console for a missing chunk under public/vendor/nova.

Name collisions with Nova's built-in Boolean. Nova 3 already ships Laravel\Nova\Fields\Boolean. Importing Naif\Toggle\Toggle is fine, but if you alias both you will fight over the Toggle short name. Import explicitly and never use ... as Boolean.

Styling with custom Nova themes. The toggle is a small CSS-driven component. If your team uses a custom Nova theme or dark mode, the track/knob colors may not meet contrast requirements — override the field's component CSS rather than patching vendor files. The extension point is to ->component('toggle-field') with your own published Vue component if you need a variant, but that requires a Nova tool/asset pipeline to compile.

Don't rely on index inline editing. If the field is not wired with Nova's UpdateField endpoint, clicking the toggle in the index does nothing. Test this per field — the safest pattern is detail/form editing with index treated as display-only.

Debugging checklist for "toggle won't save":

• Is the column in $fillable (or $guarded = [])?
• Is there an on/off accessor/mutator conflicting with the cast?
• Are you using Toggle::make('Is Active') for a column named is_active or does the field need the explicit DB column as the second argument for a differently-named attribute?
• Check storage/logs/laravel.log — Nova returns 422 with a validation error message for the specific field, which is far more useful than the UI's generic "failed to update".

Maintenance risk. With 0 dependents, 26 stars, and no release since 2021, treat this as an unmaintained convenience wrapper. For a single boolean column, Nova's built-in Boolean field gives you the same persistence with vendor support. Adopt naif/toggle only for the visual toggle, and wrap it in your own App\Nova\Toggle subclass so a future replacement (or Nova 4 migration) only touches one file.