Filament Scroll To Top Laravel Package

Getting Started

This is a small, single-purpose Filament plugin that injects a floating "scroll to top" control into a panel's rendered output. Version 1.0.2 is a patch on the 1.0.x line; the changelog entry links a compare diff with no described breaking changes, so treat it as a drop-in upgrade from 1.0.1.

Minimal setup:

1. composer require gboquizosanchez/filament-scroll-to-top — confirm the resolved version with composer show gboquizosanchez/filament-scroll-to-top before assuming the 1.0.2 behaviour, since the release notes are empty.
2. Register the plugin on the panel(s) that should get the button, in the relevant app/Providers/Filament/*PanelProvider.php:

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->plugins([
            \Gboquizosanchez\FilamentScrollToTop\ScrollToTopPlugin::make(),
        ]);
}

3. Clear cached config/blade views (php artisan filament:optimize-clear or php artisan optimize:clear) and hard-refresh — Filament caches panel configuration aggressively.
4. Publish the package config/views only if the defaults don't fit: php artisan vendor:publish --provider="Gboquizosanchez\FilamentScrollToTop\FilamentScrollToTopServiceProvider" (check vendor/gboquizosanchez/filament-scroll-to-top/README.md for the exact tags exposed in this version; the tag set is the one thing most likely to have shifted between patches).

Where to look first:

• README.md in the package root — the authoritative source for the plugin class name, config keys, and publish tags for this specific tag.
• src/ScrollToTopPlugin.php — the fluent API surface. Anything you can configure is a public method here; read it rather than guessing option names.
• resources/views/ — the Blade partial that renders the button. This is your override target.
• composer.json — the illuminate/support and filament/filament constraints tell you whether this patch is safe on your Filament major.

First use case: enable it on a panel with long resource tables and forms (a users index with 50+ rows, or a settings page with many sections), scroll down, confirm the button appears, and confirm clicking it returns you to the top without a full page reload.

Implementation Patterns

Per-panel scoping. Register the plugin only on the panels with long pages. Public-facing or auth panels rarely need it, and every panel you add it to is another place the fixed-position button can collide with other UI:

->plugins([
    ScrollToTopPlugin::make(),
])
->discoverResources(in: app_path('Filament/Admin/Resources'), for: 'App\\Filament\\Admin\\Resources')

Fluent configuration over view overrides. Prefer whatever ScrollToTopPlugin exposes (threshold, colour, icon, position) over publishing and editing the Blade view. The view is the package's internal implementation detail; a patch release like 1.0.2 can restyle or restructure it and your copy will silently go stale.

Theme integration. Point the button at your panel's primary colour so it doesn't look bolted on. If the plugin accepts a colour, pass it from ->colors([...]) using the same value. If it doesn't, this is the one legitimate case for a CSS override in your panel's custom theme:

.fi-scroll-to-top {
    background-color: rgb(var(--primary-500));
}

Conditional rendering via render hooks. For page-level control (e.g. show it on list pages but not on a full-screen dashboard), disable the plugin's own render and mount it yourself with a PanelsRenderHook scoped by page class. This is more code but keeps the decision next to the page instead of buried in panel config.

Multi-panel and multi-tenant. Register the same plugin instance shape across panels rather than sharing one configured instance object — Filament panel configs are built per-panel and reusing a mutated plugin instance across panels can leak configuration between them.

Testing. There is very little to unit-test here, but if you assert on panel HTML in feature tests, remember the button markup is now part of every panel page. Snapshot-style assertions that compare whole <body> output will break on this upgrade; scope assertions to the elements you actually care about.

Upgrade workflow. Because 1.0.2 ships no prose changelog, review the diff before bumping in a shared codebase:

composer update gboquizosanchez/filament-scroll-to-top --with-dependencies
git diff 1.0.1 1.0.2 -- vendor/gboquizosanchez/filament-scroll-to-top  # or compare on GitHub

Pin with "gboquizosanchez/filament-scroll-to-top": "1.0.*" so patches land but minors don't surprise you.

Gotchas and Tips

• Empty changelog ≠ no change. The 1.0.2 notes are only a compare link. In a patch release the realistic candidates are a view tweak, a CSS/z-index fix, or a composer constraint bump. Read the commits before assuming it's a no-op — a CSS change can break a theme override you added, and a constraint bump can change which Filament version resolves.
• Check the Filament version constraint. This plugin is thin enough that a patch release may widen or tighten filament/filament. If you're on Filament v4 or a pre-release, verify compatibility explicitly rather than assuming 1.0.x implies broad support.
• wire:navigate / SPA mode. Filament navigates client-side. A button implemented with plain JS listeners attached on DOMContentLoaded will stop working after the first Livewire navigation. If the button goes dead after clicking a nav link, that's the cause — the fix belongs in the package (a livewire:navigated listener), so check the diff for it before writing your own patch.
• Scroll position is restored on back-navigation. Browsers and Livewire may restore scroll offset, which can leave the button visible on a page you just arrived at. Verify the visibility threshold logic, not just the click behaviour.
• Fixed-position collisions. The button competes for the bottom-right corner with Filament's own notifications, debug tools, and any chat/support widget. Symptom is overlapping or unclickable controls; remedy is offsetting one of them via CSS custom property rather than fighting z-index.
• z-index inside modals. Filament renders modals above normal page chrome. A button with a high z-index can float over an open modal — check that the package hides it when a modal is open, and if not, hide it yourself on modal-open events.
• Dark mode. Custom colour overrides that hardcode hex values will look wrong in dark mode. Use Filament's CSS variables (--primary-*, --gray-*) so the button inherits both themes.
• Caching. After changing panel config or publishing views, php artisan optimize:clear is mandatory — stale bootstrap/cache/config.php is the single most common "the plugin isn't doing anything" cause.
• Assets. If the package ships CSS/JS through FilamentAsset, remember those are served from public/ and need php artisan filament:assets (or an filament:upgrade) after a version bump in production deploys.
• Extension points, in order of safety: fluent plugin methods → render hook replacement → published view override → CSS override. Going further down that list increases the chance a future patch breaks you, and with a package this small you may eventually prefer inlining a 30-line Blade partial plus a tiny Alpine component into your own panel and dropping the dependency.