Product Decisions This Supports
- Roadmap: "polish sprint" scoping. This package turns a vague "our admin UI looks dated" complaint into a concrete, bounded ticket: one Composer require, zero configuration. It's the kind of item you can slot into a hardening/polish sprint instead of carving out real feature capacity.
- Build vs. buy vs. copy. The honest framing is build ≈ buy. The package is ~20 lines of pure CSS that shims
scrollbar-width / scrollbar-color and ::-webkit-scrollbar pseudo-elements. The "buy" decision here is really "do we spend 30 minutes of anyone's time on this at all, and whose time?" — and the answer is almost always yes if you're already deep in a Filament admin.
- Perceived quality of customer- and exec-facing panels. If your Filament panel is part of the product (client portals, internal tools demoed to buyers, ops dashboards shown in reviews), scrollbar chrome is a visible, low-effort signal of craft. Cheap win; not a differentiator, so keep it out of marketing and release notes.
- Design-system consistency backlog. Scrollbars are one of several "native browser chrome" surfaces (selection color, focus rings, form controls) that a design system has to own or deliberately ignore. Adopting this is a decision to not hand-roll that slice, and to defer the "we need a real theme/design-token pass" conversation by one more quarter.
- Support and QA cost. Marginal — but it removes a recurring class of "the sidebar scrollbar is enormous / invisible in dark mode" feedback from non-technical admins.
- Version-lock decisions. The one real choice is the major-version matrix (Filament 3/4/5 →
^2.x; Filament 2 → ^1.x). That's a compatibility gate for any panel you're still running on an older Filament branch — worth flagging if you have more than one panel in flight.
- Explicit non-decision: this should never be a dependency you plan a migration around. Treat it as a snippet you happen to install.
When to Consider This Package
Adopt when:
- The app is on Filament 3.x, 4.x, or 5.x and the admin panel is seen by people outside engineering.
- You have no established custom Filament theme, or your theme has no scrollbar treatment.
- You want zero maintenance surface and zero JavaScript — this adds nothing to the runtime bundle and nothing to your upgrade burden.
- You're doing a UI/visual QA pass anyway, so the verification cost (light mode, dark mode, Firefox, mobile, custom-theme panels) is amortized over other work.
Look elsewhere (or just copy the CSS) when:
- You already run
->viteTheme(...). If you maintain a custom theme file, inline the ~20 lines and drop the dependency. You get the same result, one fewer vendor, and no single-maintainer risk. This is the strongest argument against installing it.
- Accessibility is a hard requirement. Thin scrollbars are a usability tradeoff for low-vision and motor-impaired users, and hover-revealed or low-contrast thumbs are worse. If you're under WCAG obligations or have an accessibility audit on the roadmap, don't ship a cosmetic scrollbar override without a deliberate review — and prefer
scrollbar-width: thin with a guaranteed-contrast thumb over hover-only appearance.
- Panels use JavaScript custom-scroll libraries (OverlayScrollbars, perfect-scrollbar, virtualized tables). Native CSS scrollbar rules won't apply; you'll get inconsistent results and a false sense of "done."
- Mobile is your primary surface. Since 2.1.0 the treatment is wrapped in a large-screen media query, so phones are intentionally untouched — good behavior, but it means this is a desktop-only win.
- Procurement/supply-chain policy requires vendored or audited code. 51 stars, a single maintainer, 0 listed dependents, and a changelog dominated by Dependabot bumps. That's fine for a CSS primitive and unacceptable as a load-bearing dependency — which is exactly why the copy-in approach is the mature call for larger orgs.
- You need per-panel control. This is global-on-install; scoping it to one panel means writing your own CSS anyway.
- The team has no Filament panel at all — obvious, but worth stating so this doesn't get picked up on "looks nice" grounds alone.
How to Pitch It (Stakeholders)
For executives (30 seconds): A tiny, free, MIT-licensed visual fix that makes our Filament admin panel look more modern — slimmer scrollbars in the sidebar, tables, and every scrollable area, matching both light and dark mode. Cost is roughly half an hour of engineering and a one-line composer.json change. No JavaScript, no performance impact, no configuration, removable in one command if we dislike it. We already have the polish work on the board, so this rides along at near-zero marginal cost. It is not a feature and shouldn't be measured as one — it's hygiene.
For engineering (the real pitch): Pure-CSS package that registers a stylesheet through Filament's asset pipeline on service-provider discovery. No vendor:publish, no config file, no PanelProvider changes, no JS, no dependencies. Compatible with Filament 3/4/5 (^2.x) and 2.x (^1.x). Verification is four checks: light mode, dark mode thumb contrast, Firefox (scrollbar-width/scrollbar-color path), and a narrow viewport (mobile is deliberately excluded via a min-width: 1024px media query). Two caveats to accept up front: panels with a custom Vite theme may silently miss the injected CSS and need it copied in, and the package is single-maintainer — so the recommended end state for teams with a theme file is to inline the rules and remove the dependency. Install it today as the fast path; own the CSS tomorrow when you next touch the theme.