Filament Sticky Header Laravel Package

Technical Evaluation

Architecture fit

• A single-purpose Filament Panel plugin: one service provider registers scoped CSS/JS assets and the panel-level StickyHeaderPlugin object. No models, migrations, routes, config publishing, or database footprint.
• Behavior is delivered primarily through CSS (position: sticky plus theme variants) backed by a small amount of JavaScript (intersection observation to prevent header bounce, re-initialization on Livewire wire:navigated SPA transitions).
• Configuration is fluent and code-level (floating(), colored(), stickOnListPages(), disabledOn()), including Closure support for per-user or runtime-conditional behavior. This fits the Filament idiom cleanly and keeps decisions in version control rather than in a settings UI.
• The plugin's scope is presentation-only. It is a UX-polish dependency, not a platform component — appropriate classification given 83 stars, 0 dependents, and a composite score of ~29.5.

Integration feasibility

• High, conditional on one gate: the consuming panel must run a custom Filament theme. The plugin's views/CSS must be imported into the theme CSS file (@import '../../../../vendor/awcodes/filament-sticky-header/resources/css/plugin.css'). Panels using Filament's default compiled theme cannot consume it without first standing up a theme build.
• Once a theme exists, integration is a two-line change: composer require awcodes/filament-sticky-header and StickyHeaderPlugin::make() in the panel's plugins() array.
• Multi-version support is a genuine positive: release line 4.x declares compatibility with both Filament 4.x and 5.x on a single branch, which materially reduces the cost of an upcoming Filament major upgrade. Prior lines map cleanly (3.x→Filament 4, 2.x→Filament 3, 1.x→Filament 2), so the compatibility matrix is legible and predictable.

Technical risk

• CSS coupling to Filament internals (primary risk). Sticky positioning depends on matching Filament's header/body container classes and DOM structure. Upstream Filament markup or Tailwind changes can silently degrade the header into overlap, duplicate rendering, or no-op sticky behavior. The changelog shows this class of defect repeatedly (menu toggle, sticky top bar, alignment, bottom padding, filter icon z-index, notification overlay z-index).
• Z-index/stacking regressions. A fixed header competes with modals, dropdowns, notifications, and the topbar. History shows multiple fixes here; each new Filament release is a re-test candidate.
• Theme build fragility. Importing vendor CSS into a Tailwind pipeline can be purged or misordered depending on Tailwind version and content-scanning configuration, producing a plugin that "installs" but does nothing visible.
• Bus factor and validation. Single maintainer, no advertised test suite, 0 dependents, and a release history dominated by Dependabot bumps — maintenance is real but thin. MIT license and small surface area make an in-house escape hatch cheap.
• Accessibility risk (under-documented). A sticky header can occlude anchor/focus targets; there is no documented scroll-margin-top guidance, reduced-motion consideration, or mobile viewport handling (notably iOS dynamic viewport height).

Key questions

1. Which Filament major (4.x or 5.x) is in production, and is a custom theme already maintained, or would this introduce a new build artifact we must own?
2. What Tailwind version backs the theme, and has the vendor CSS import been verified as surviving the production build?
3. Is SPA mode enabled? Does wire:navigated re-initialization hold across our page types (resources, custom pages, relation managers)?
4. Do we need sticky behavior on list pages with large/high-row-count tables, or should stickOnListPages(false) be the default to avoid perceived scroll jank?
5. What is the acceptable fallback if the package is abandoned — hand-rolled sticky CSS in our own theme (~10–20 lines) versus forking?
6. Are there pages with complex stacking contexts (custom widgets, embedded charts, third-party JS) that need explicit disabledOn() exemptions?

Integration Approach

Stack fit

• Laravel + Filament Panels, Composer-managed, standard package discovery. No host application code changes beyond the panel provider and the theme stylesheet.
• The fluent, closure-capable API aligns with existing Filament configuration conventions, so it can be gated behind existing feature-flag or user-preference patterns without new infrastructure.
• No interaction with tenancy, authorization, queues, storage, or the data layer — blast radius is confined to rendered chrome.

Migration path

• Purely additive; no data migration, no schema change, no route change. Rollback is removing the plugin registration (the CSS import can remain inert, or be dropped in a follow-up build).
• Practical sequencing:
  1. Confirm/create the custom theme and validate the build pipeline in a preview environment.
  2. Add the Composer dependency with a pinned constraint (^4.2), committed lockfile.
  3. Add the @import to the theme CSS and rebuild; verify assets appear only in panel context (the v3.1.0/v4.1.0 fix scoped JS registration to panels — confirm this holds for our multi-panel setup).
  4. Enable StickyHeaderPlugin::make() with no theme options first; smoke-test scrolling on a long resource edit page and a list page.
  5. Layer on floating()/colored() behind a preference or flag; validate against modals, notifications, and the topbar.
  6. Apply stickOnListPages(false) and disabledOn([...]) exemptions based on QA findings.
  7. Ship to one panel first, then fan out.

Compatibility

• Pin to the 4.x line for Filament 4/5 dual support; do not adopt 3.x if a Filament 5 upgrade is on the roadmap.
• Add the package to the Filament-upgrade regression checklist: any Filament minor upgrade requires a visual pass on sticky behavior, stacking order, and mobile viewports.
• If the application runs multiple panels (admin, vendor, customer), verify per-panel registration and confirm no cross-panel asset bleed.

Sequencing relative to other work

• Low-priority, non-blocking. Best scheduled alongside an existing theme or Filament-upgrade initiative where the custom theme prerequisite is already being paid for. Do not let this package be the sole justification for introducing a theme build.

Operational Impact

Maintenance

• Ongoing cost is small but not zero: Composer updates, theme rebuild verification after Filament upgrades, and periodic visual QA. Expect roughly a few hours per Filament minor release.
• The upstream repo is actively touched (recent releases through v4.2.0, including a CI refresh and dual Filament 4/5 support), but changes are largely dependency automation. Treat the maintainer as responsive-but-unsupported, not as a vendor.
• Recommend recording the fallback: replacing the plugin with a short block of sticky CSS in our own theme. This keeps the dependency fully reversible and bounds the abandonment risk.

Support

• Community-only: GitHub issues, no SLA, no commercial backing. Internal ownership should sit with the team that owns the Filament theme.
• Because the plugin's contract is visual, "support" really means "who re-verifies the header after each Filament upgrade" — name that owner explicitly.

Scaling

• Server-side impact is negligible (asset registration only). No measurable request, query, or memory cost.
• Client-side cost is a sticky-positioning layer plus an intersection observer — trivial on typical admin pages. The realistic scaling concern is perceived performance on long, high-row-count list pages, where a fixed header reduces usable viewport and can amplify scroll jank on low-end mobile devices. Default stickOnListPages(false) is the safer posture for data-heavy panels.
• Multi-panel and multi-tenant deployments scale fine, but each panel's provider must be configured independently, which is a configuration-drift surface.

Failure modes

Ramp-up

• Very low. A developer familiar with Filament can complete installation and configuration in well under an hour; the only prerequisite knowledge is Filament's custom-theme setup, which is documented upstream.
• No training, runbook, or on-call implications. Communicate the change to admin users only insofar as it alters scroll behavior on long forms — expect minor subjective feedback on the floating/colored variants, so ship those behind a preference rather than as a hard default.