- How do I install awcodes/light-switch in a Laravel Filament panel?
- Install the package with composer require awcodes/light-switch, then register the plugin in your panel provider by adding LightSwitchPlugin::make() to the Panel::plugins() array. After that, add the plugin's @source path to your custom theme CSS file so Tailwind compiles its Blade views, and rebuild your assets with Vite. There is no service provider to publish, no config file, and no migrations, so the whole install is usually under an hour once a custom theme exists.
- Which Filament versions does awcodes/light-switch support?
- Compatibility is strictly pinned by package major version: 1.x targets Filament 3, 2.x targets Filament 4, and 3.x targets Filament 4 and 5 per the README compatibility table. There is no single release that spans Filament 3 through 5, and no LTS branch, so every Filament major upgrade forces a coordinated plugin upgrade. Check the tagged release that matches your Filament version before running Composer.
- Why do I need a custom Filament theme to use this plugin?
- The package ships uncompiled Blade views and relies on your theme's Tailwind build to scan and compile its classes via the @source directive. Without a custom Filament theme in place, the toggle markup renders but the styles may never be generated. If your team has never built a Filament theme, that prerequisite is usually the largest part of the work, bigger than the plugin installation itself, so budget for it in the estimate.
- Which auth pages show the light, dark, system switcher?
- By default the switcher is injected into the Filament panel authentication pages: login, register, password reset, and email verification. It does not appear on the authenticated panel, resource pages, or any application views. Note that the v2.0.1 changelog removed the profile view from the default show list even though the README example still references it, so confirm behaviour against the tagged source you install.
- How do I change the position of the theme switcher on the login page?
- Pass one of the Alignment enum cases to the position() method when registering the plugin, for example LightSwitchPlugin::make()->position(Alignment::BottomCenter). Import Awcodes\LightSwitch\Enums\Alignment to access the available cases. The default placement is the top right of the auth pages.
- How do I restrict the switcher to specific auth pages with enabledOn()?
- Pass an array of route strings to the enabledOn() method, and the switcher will only render on routes in that list. Be aware that this replaces the default list rather than adding to it, so include every route you still want covered. The README's section on disabling pages describes passing route strings to an on() method while the example uses enabledOn(), and the described behaviour is the inverse of the sample, so read the source before relying on it.
- Does the theme switcher remember a user's choice across devices or accounts?
- No. The selected mode is stored browser-side only, and system mode delegates to the operating system's prefers-color-scheme setting. There is no database write, no config store, and no server-side preference table, so the package cannot deliver account-level or cross-device theme persistence. If a requirement says remember my theme, scope it to this browser or plan a custom implementation.
- The toggle is rendering unstyled or blank after install. What went wrong?
- The most common cause is a missing or incorrect @source line in your theme CSS, which means Tailwind never scans the plugin's Blade views and none of its utility classes are generated. The path is relative to your CSS file, so adjust the number of ../ segments if your theme lives elsewhere. Also rebuild assets after adding it, and clear any cached views or compiled CSS. Failures here are visual rather than exceptions, so a quick browser check after each Filament upgrade is worthwhile.
- Is awcodes/light-switch safe and maintained enough for production?
- It is a small, single-purpose plugin from a known Filament contributor, but the repository has a modest star count and few dependents, so it is effectively a single-maintainer project. The listed last release date is in the future, which is an anomaly worth verifying against Packagist release history and commit activity before committing. Because the plugin only touches auth views, a failure is contained and easy to remove, which keeps the blast radius small in production.
- Are there alternatives if I need theme switching across the whole dashboard, not just auth pages?
- This package is scoped to Filament panel auth pages only and is not a general Laravel theming library, so whole-panel or app-wide dark mode needs a different solution such as Filament's own theme configuration or a custom toggle component. Also note the plugin requires Filament Panels; if you only use Filament Forms or Tables without a panel, this package is not applicable. For auth-page-only switching, the alternatives are largely hand-rolled Blade toggles that you maintain yourself.