Weave Code
Dark Mode Laravel Package
laravel-ux/dark-mode
Add dark mode to Laravel apps with a simple toggle UI and persistent user preference. laravel-ux/dark-mode offers a lightweight, Blade-friendly setup for theme switching, helping you deliver comfortable light and dark experiences without custom JavaScript.
Dark mode support for Laravel Blade and Livewire applications.
Frequently asked questions about Dark Mode
- How do I install laravel-ux/dark-mode in a Laravel application?
- Install it with Composer using the package name laravel-ux/dark-mode, and pin the exact 0.1.0 release rather than a caret range because the package is pre-1.0. Your app should already use Laravel with Blade, Livewire, Alpine, Tailwind configured with darkMode: 'class', and the Laravel UX UI and Icons components. Confirm that dependency stack before adoption, since the UX UI and Icons requirement is the most likely blocker for teams with an existing design system.
- Which Laravel, Livewire, Alpine, and PHP versions does laravel-ux/dark-mode support?
- The package is at v0.1.0 and is described as fitting Livewire v3-era Laravel apps, but the provided information does not include a complete PHP, Laravel, Livewire, or Alpine compatibility table. Verify the supported matrix in the repository before committing, and pin the exact 0.1.0 version. It also pulls in Alpine and the Laravel UX UI and Icons components, so each is an independent upgrade vector to check.
- Where should I put @darkModeScripts in my Blade layout?
- Place the @darkModeScripts directive in the head before first paint, ahead of the relevant Livewire and Alpine script tags, because it is the load-bearing piece that prevents a theme flash. Add the toggle component, with the ux.dark-mode::toggle alias, in your navigation or another appropriate UI location. Also enable Tailwind's darkMode: 'class' strategy so the root dark class actually drives styles.
- Does laravel-ux/dark-mode work with Tailwind CSS?
- Yes, it fits Laravel apps that use Tailwind's darkMode: 'class' strategy, where the package owns the root dark class and toggles it. It is a poor fit for apps using prefers-color-scheme-only theming or non-Tailwind CSS stacks. If your design system does not already use class-based dark mode, plan the styling changes before adopting the package.
- Does laravel-ux/dark-mode work with Livewire and Alpine, including wire:navigate?
- It is designed for Blade, Livewire, and Alpine apps and includes a session-persisted Livewire toggle plus an Alpine store bridge. The package deliberately spans server session, Alpine store, and DOM class state, which is the right design for Livewire but creates cross-cutting state to test. Pay special attention to wire:navigate soft reloads, because the Alpine store and toggle state may reinitialize or desync; verify behavior in your app.
- Does laravel-ux/dark-mode persist a user's dark mode preference?
- Yes, it persists the preference in the Laravel session and also bridges state through an Alpine store and the root dark class. That three-channel design is intentional for Livewire apps, but it means existing localStorage keys or hand-rolled class writers can conflict during migration. Audit any incumbent preference storage before adopting the package.
- Will laravel-ux/dark-mode cause a flash of the wrong theme on first paint?
- First-paint correctness is a real risk because the initial class may be server-derived from session, and the inline script must render early enough to avoid a flash. The @darkModeScripts directive is load-bearing: if it is late, blocked by CSP, skipped by a full-page cache, or not CSP-nonce aware, users may see the wrong theme. Test head placement, cache behavior, and CSP handling explicitly. Check whether the dark class is server-rendered, client-rendered, or both, since that affects full-page-cache viability.
- Can I retrofit laravel-ux/dark-mode into an app that already has custom dark mode?
- Retrofitting is materially harder than adopting it in a greenfield app. Two writers to the same dark class and two listeners on the same storage key will fight, and session-backed state may disagree with localStorage. Audit and remove the incumbent implementation first, including localStorage keys, media-query listeners, class writers, and inline head scripts, then migrate the stored preference. Do not run both implementations in parallel.
- Is the laravel-ux/dark-mode toggle accessible?
- The package provides the Laravel UX UI toggle component, but the provided information does not spell out the exact accessibility contract for role, aria-pressed or aria-checked, keyboard behavior, focus ring, and contrast. Review the rendered component and test it with a keyboard and a screen reader before relying on it. If your app has strict accessibility requirements, treat the toggle markup as something to verify rather than assume.
- Is laravel-ux/dark-mode ready for production at v0.1.0?
- Treat v0.1.0 as pre-1.0 software: the directive name, component alias, event name, and store key are public contract with no stability guarantee, so pin the exact version. Production risk is concentrated in first-paint correctness, state reconciliation across session, Alpine, and DOM, wire:navigate behavior, CSP, and full-page caching. The provided information does not include maintainer details, release cadence, or a support window, so review repository activity and release notes before committing. Test the integration in a staging environment with your actual cache and CSP setup.
Weaver
How can I help you explore Laravel packages today?