Simple Statamic Toolbar Laravel Package

Getting Started

The toolbar injects a small floating bar into your front-end pages so logged-in Control Panel users can jump straight to the CP entry, edit the current page, or open the site's CP home — without hunting for the URL.

composer require chrisvasey/simple-statamic-toolbar

There is nothing to compile. Since v1.3.0 the toolbar ships its own JavaScript as a published, cache-busted asset — no Alpine.js and no Tailwind CSS are required in your site's front-end bundle. If you previously added either dependency purely to satisfy the toolbar, you can drop it from your build.

Then publish whatever the addon exposes:

php artisan vendor:publish
# pick the SimpleStatamicToolbar provider, or use the tags listed
# in the publishes() array of the addon's ServiceProvider

First thing to look at:

1. vendor/chrisvasey/simple-statamic-toolbar/config/ — which environments/collections gate the toolbar, and any asset/route settings.
2. vendor/chrisvasey/simple-statamic-toolbar/resources/views/ — the toolbar template. This is the file you publish and override.
3. vendor/chrisvasey/simple-statamic-toolbar/resources/js/ — the front-end behaviour, if you need to know the storage keys or the expand/collapse contract.

First use case: log into /cp in one browser tab, open any front-end page in another, and click the toolbar's edit link. It should land you on the matching entry in the Control Panel. If it doesn't appear, check that you are authenticated in the CP, that the environment isn't excluded in config, and view the raw page source — the toolbar is injected server-side before </body>, so it should be visible in source even with JS disabled.

Implementation Patterns

Trust the automatic injection, override only when needed. The toolbar is appended to the rendered response body, so it works across Antlers layouts, Blade views, and anything else that outputs HTML. Publish the view only when you actually need to change wording, icons, or extra links — otherwise you inherit upstream fixes for free.

Template override workflow (v1.3.0 respects it). Publish the view into resources/views/vendor/simple-statamic-toolbar/, edit it, and keep the structural hooks (data- attributes, aria-expanded/aria-controls on the toggle button, class names the bundled JS expects). If you remove the toggle button markup, the persisted expand/collapse preference has nothing to bind to. Clear the view cache after editing:

php artisan view:clear

Gate it by environment. The toolbar is an editor tool, not a feature. Keep it enabled in local/staging and either disable it or restrict it to super users in production. If the config allows per-collection or per-route exclusions, use those rather than wrapping every layout in a conditional — it keeps the layout clean and survives template refactors.

Subdirectory installs work now (v1.3.0). If you host Statamic under a path prefix (e.g. /cms or /site), the CP links previously resolved to the wrong root. Make sure APP_URL includes the subdirectory and that your web server passes the correct SCRIPT_NAME/prefix — the fix removes the addon's contribution to the bug, not configuration problems on your side.

Explicit placement. If you need the toolbar in a position other than the end of <body> — or you have pages where body injection is inappropriate — check resources/views for a partial or Antlers tag you can render manually and disable the automatic injection in config. This is the cleaner option for anything with an unusual document structure.

Pair it with your local dev loop. Because the JS is a separate cache-busted asset, a hard refresh is usually enough after an upgrade; no npm run build step in your site's pipeline is involved. php artisan statamic:stache:clear plus a browser refresh covers most "it didn't change" cases.

Gotchas and Tips

Full-page caching is the big one. If you use Statamic's static caching or a response cache, the toolbar HTML can be baked into the cached copy and served to anonymous visitors (or cached without it and never shown to editors). Exclude authenticated CP sessions from the cache, or exclude the toolbar from the cached output and render it only on cache misses for logged-in users. Verify with an incognito window after warming the cache.

Body-tag detection is improved, not infallible. v1.3.0 handles mixed-case </BODY> and preserves embedded script contents, but the classic failure mode remains: a literal </body> inside an inline <script>, a <template>, or an HTML comment can still confuse naive injection. If a page's inline JS breaks after installing, that's the first place to look — compare the page with the toolbar disabled.

Non-HTML responses are silently skipped. Streamed responses, file downloads, and JSON endpoints bypass the injection. That's correct behaviour, but it means a page rendered via response()->stream() won't show the toolbar and there is no error to point that out.

Upgrading from v1.2.x: if you had styled the old toolbar with Tailwind utility classes in your own CSS, or relied on Alpine directives in a custom override, those selectors and attributes no longer exist. Re-publish the view, diff it against your override, and port your customisations onto the new markup. Keep the aria-* attributes — the new toggle is keyboard accessible and removing them regresses that.

Re-publish the asset after upgrades. The JS is published, not served from vendor/. After composer update, confirm the published asset matches the new version (re-publish with --force if the addon doesn't auto-refresh it), otherwise you're running new PHP against old JS and the expand/collapse state will misbehave.

The expand/collapse preference is per-browser, not per-user. It almost certainly lives in localStorage, so it doesn't follow an editor between machines, doesn't survive a cleared cache, and won't apply in an incognito session. If you change the toolbar's markup structure, bump or clear the storage key so stale stored state doesn't render an expanded bar with collapsed markup.

Verify permission-dependent links, not just presence. Editors, authors, and super users get different CP links depending on what they can access. Test with a non-super role — the toolbar may render a link the user then gets a 403 on.

Version support: v1.3.0 is CI-tested against Statamic 5 and 6. If you're still on Statamic 4, pin to the older release line rather than upgrading blind.

Debugging checklist: view raw source (not the DOM inspector) to confirm server-side injection → disable JS to confirm the base markup renders → check storage/logs/laravel.log for view-rendering errors from a broken override → php artisan view:clear after any template edit.