Wire Bootstrap Laravel Package

Getting Started

This release is a styling/theme release more than an API release — nothing in the component's surface changed, but if your app uses dark mode or a non-default Bootstrap $primary, 1.0.1 is the version where the calendar finally matches your UI instead of rendering a white sheet with dark text.

1. Upgrade as usual (composer update) and rebuild assets (npm run build / npm run dev). The new SCSS file ships in the package's resources/scss/ directory.

2. If you installed before 1.0.1, open resources/scss/app.scss and add the theme import by hand, after the vendor/Bootstrap styles:

   @import 'bootstrap/scss/bootstrap';
   @import 'flatpickr/dist/flatpickr.css';        // vendor
   @import '.../wire-bootstrap';                  // ← add this, after vendor styles
   

   Fresh installs get this line in the published app.scss stub automatically, so re-running the installer (php artisan vendor:publish --tag=... --force) is the quickest way to see the intended ordering — but read the diff before force-overwriting your own customisations.

3. Look first at the published app.scss stub if you're unsure where the import belongs; it's the canonical example of load order.

4. First use case worth verifying: drop your existing date input into a dark-mode page (<html data-bs-theme="dark">) and open the calendar. Days, in-range highlights, today, the month/year dropdowns, week numbers and the time picker should all inherit your theme — that's exactly the bug fixed here. If it still looks light, your import is either missing or loaded before flatpickr's own stylesheet.

Implementation Patterns

Theme via CSS variables, not SCSS overrides. The whole point of this layer is that it reads Bootstrap 5.3 custom properties (--bs-body-bg, --bs-primary, etc.) rather than hardcoding colours. Customise by setting the brand color once — $primary at SCSS compile time, or --bs-primary at runtime — and the calendar follows. Avoid writing .flatpickr-day { background: #0d6efd } overrides; they'll fight this file and break the moment you add a second theme.

Dark mode is free if you use data-bs-theme. Because the stylesheet is variable-driven, a runtime theme toggle (document.documentElement.dataset.bsTheme = 'dark') re-themes the calendar without re-instantiating flatpickr. Keep theme switching in that idiom rather than swapping stylesheets; swapped stylesheets will leave already-rendered calendars stale.

Form integration. Typical use is a Blade component bound to a wire:model. Keep the underlying input a plain input.date so the package's styles apply, and prefer wire:model.blur (or .defer) over .live — flatpickr fires on every keystroke as you type a date, which makes .live chatty and can momentarily push invalid partial dates into your Livewire state.

Server-side normalization. Pick one date format in config and mirror it in your validation ('date_format:Y-m-d'). If the picker displays a localised format to users, rely on the picker's alternate-input/altFormat behaviour so the value posted to the server stays ISO — don't do display formatting in the Livewire component.

Ranges and constraints. For booking-style flows, wire range mode plus minDate/maxDate from Livewire state, and re-render the picker when that state changes (keyed @if/wire:key is the cheapest way to force a re-init). Fetch disabled dates from your backend rather than hardcoding them in Blade.

Composition with other UI. Drop the date input inside your standard Bootstrap input-group with a form-control class and a trailing calendar icon button; the theme layer styles the popup, and your surrounding markup stays ordinary Bootstrap. For time pickers, enable enableTime and align the time picker's variables with the same primary so the two panels don't diverge.

Gotchas and Tips

• Upgrade path is the gotcha. Existing apps do not get the new import automatically — the release notes say so explicitly. If you upgrade and dark mode still looks broken, you haven't added the import; nothing is wrong with the package.
• Import order matters. The theme layer must come after flatpickr's own CSS. If your bundler hoists or you use @use with a shared entrypoint, verify the compiled order in public/build rather than trusting the source order.
• CSS variables must be in scope. Variables are resolved against the element the calendar lives in. If flatpickr is configured to append to a container outside <html data-bs-theme> (or inside a shadow root / isolated wrapper), it will fall back to light defaults. Keep the popup appended to body or a themed ancestor.
• Rebuild after every change. SCSS edits won't appear until Vite/Herd/Mix rebuilds; a cached public/build is the #1 cause of "the fix didn't work". npm run build then hard-refresh before debugging anything else.
• --force on publish. Re-running the installer to get the updated app.scss stub will overwrite your file. Prefer copying the import line across manually; only --force on a clean checkout.
• Livewire + picker state drift. If the input is updated programmatically (validation reset, $wire.set, modal reopen), the visible picker can retain the old date. Call the picker's setDate/clear in a $wire.on or x-init hook rather than setting value on the DOM node.
• Debugging theme problems. Inspect the open calendar's .flatpickr-calendar element and check which custom properties are computed on its ancestors. If --bs-body-bg is empty there, the problem is scoping or import order, not the theme file.
• Extension point. Because this is a plain SCSS layer and not a compiled bundle, forking it into your own resources/scss/ and adjusting selectors is cheap and safe — but pin the package version so a future theme release doesn't silently duplicate or conflict with your fork.
• Accessibility nudge. The theme file handles colour contrast; it doesn't add labels. Keep an associated <label for> or aria-label on the input, since flatpickr's popup is easy to operate visually and impossible otherwise.