Statamic Frontend Grid Fieldtype Laravel Package

Getting Started

This addon adds a Grid fieldtype to Statamic's control panel, letting editors compose front-end grid layouts (columns/rows of blocks) as structured content rather than raw HTML. Version 1.0.0 is the first stable release and, importantly, is a Statamic 6 compatibility release.

Minimum steps:

1. composer require mitydigital/statamic-frontend-grid-fieldtype
2. Confirm you're on Statamic 6 (statamic/cms:^6.0) and a compatible PHP/Laravel baseline (Statamic 6 requires PHP 8.2+ and Laravel 11/12). If you're still on Statamic 5, pin to ^0.0.4 instead — 1.0.0 is not a drop-in for v5.
3. The addon's service provider is auto-discovered; no manual registration should be needed.
4. Publish any config/views if the README instructs it: php artisan vendor:publish --tag=statamic-frontend-grid-fieldtype (verify the exact tag — it varies by addon).
5. Add the fieldtype to a blueprint (Pages collection is the natural first target), pick the field handle (e.g. grid), and configure the available sets/blocks.

Where to look first:

• The README for the fieldtype handle and blueprint YAML example.
• config/statamic/frontend-grid.php (if published) for layout/breakpoint defaults.
• resources/js/ in the package if you need to understand the CP Vue component — useful when you're debugging why a block type isn't appearing.

First use case: a page-level "content grid" where marketing can add rows of cards/columns without a developer, and your Antlers/Blade template loops over the field to render a consistent layout.

Implementation Patterns

Blueprint-first configuration. The fieldtype is only as good as its blueprint config. Define the allowed block types/sets once in a fieldset and reuse it across collections rather than duplicating YAML per-blueprint. This keeps the editor UI consistent and makes future schema changes a single-file edit.

Render through a partial per block. The clean pattern is a top-level grid partial that iterates rows, which iterates columns, which includes a partial keyed on the block type:

{{ grid }}
    <div class="grid grid-cols-{{ columns | count }}">
        {{ columns }}
            {{ partial src="grid/{type}" }}
        {{ /columns }}
    </div>
{{ /grid }}

(Exact tag names come from the fieldtype's own data shape — read the README's rendering example before assuming.) Mirror this in Blade with @include if your project is Blade-first.

Treat layout as data, not markup. Keep column widths/breakpoints in the field config and map them to Tailwind (or your CSS) classes in the partial. Don't let editors inject arbitrary classes unless the fieldtype explicitly offers a class field — that's an XSS/design-drift vector.

Compose with existing Statamic features. The grid fieldtype pairs well with:

• Sets for repeatable block types (card, image, quote).
• Fieldsets for shared grid definitions across collections.
• Multi-site: confirm whether grid content is localizable or shared before promising per-locale layouts to editors.

Cache the output, not the field. Grid content is just YAML in the entry's markdown file, so Statamic's stache already handles read performance. If your grid partial is expensive (image transforms, relation lookups), cache the rendered partial rather than reaching for a custom query layer.

Gotchas and Tips

1.0.0 is a hard Statamic 6 gate. The only change in this release is the Statamic 6 update. Do not bump the constraint on a Statamic 5 project expecting it to work — check composer.json requirements and keep ^0.0.4 on v5. Conversely, if you're upgrading to Statamic 6, this is the version you need.

Expect 0.0.x → 1.0.0 drift. The jump from 0.0.4 to 1.0.0 signals API stability, which usually means at least some config keys or set-handle conventions were normalized. Diff your blueprint YAML against the new README after upgrading; silently ignored keys are the most common failure mode (the field renders, but blocks don't appear).

Cache clears are non-optional. After changing the fieldtype's blueprint config or upgrading the package, run php artisan statamic:stache:clear && php artisan view:clear. Fieldtype registration and Vue component assets are cached; a stale stache produces "fieldtype not found" or an empty editor panel that looks like a bug but isn't.

Renaming field handles loses data. Grid content lives under the field handle in the entry's front-matter. Renaming grid to content_grid orphans the existing YAML. Migrate with a one-off command or leave the handle alone.

Asset publishing for CP changes. If the control-panel UI misbehaves after an upgrade (missing icons, broken drag handles), republish the addon's public assets — CP Vue bundles are served from public/vendor/, not node_modules, and are easy to leave stale. php artisan vendor:publish --force for the addon's tag, then hard-refresh the CP.

Extension points worth knowing. Before forking: check whether the addon exposes config for default breakpoints and available sets (usually the intended customization surface), and whether views can be overridden via resources/views/vendor/{package}/. Most "I need to change how it renders" requests should be solved by overriding the view or the partial, not by subclassing the fieldtype.

Debugging the fieldtype itself. If editors report a blank grid UI, check the browser console first — a failed CP asset load (404 on the addon's JS) looks identical to a config error. Then inspect the entry's YAML to confirm data is being saved at all; if it is, the problem is rendering, not the fieldtype.