Statamic Group Laravel Package

Getting Started

eminos/statamic-group is a Statamic addon that adds a group fieldtype for visually grouping related fields inside a blueprint. It is presentation-only: fields still save to their own handles under the parent fieldset.

Install with Composer:

composer require eminos/statamic-group

Version v2.1.0 adds Statamic 5 support. Confirm your statamic/cms constraint allows Statamic 5 before upgrading, then run migrations/caches as usual:

php artisan cache:clear
php please stache:clear

First use case: open a blueprint (e.g. resources/blueprints/collections/pages/page.yaml) and wrap a related set of fields in a group instead of scattering them down a long sidebar:

sections:
  main:
    display: Main
    fields:
      -
        handle: seo
        type: group
        display: SEO
        fields:
          -
            handle: meta_title
            type: text
          -
            handle: meta_description
            type: textarea

Look first at the package README for the exact supported group options (fields, display/layout settings, collapsed state), then check the generated field UI in the Control Panel. Because groups are a CP convenience, the quickest validation is to edit an entry and confirm the nested fields render and save correctly.

Implementation Patterns

Group related CP fields, not data models. Use a group to collect fields that belong together editorially — SEO metadata, hero content, callout settings — while keeping each nested field's handle unchanged. Existing templates and queries continue to use the same handles.

Reuse groups through fieldsets/partials. If several blueprints need the same grouped block, define the group once in a reusable fieldset or YAML partial and import it. This keeps the CP layout consistent across collections and taxonomies.

Nest groups sparingly. One level of grouping is usually enough. Deeply nested groups make blueprints harder to reason about and can make conditionals and validation messages confusing for editors.

Combine with sections and tabs deliberately. Sections remain the top-level layout primitive; groups are best for sub-clusters inside a section. Avoid using a group as a substitute for a tab when the real need is a separate editing context.

Use in blueprints, fieldsets, and other fieldtype-driven configs. The fieldtype can be used anywhere a normal blueprint field list is accepted. For programmatic blueprints, add the same type: group array structure in PHP rather than hand-building HTML.

Upgrade path for Statamic 5: update the addon to ^2.1, ensure the app's Statamic constraint is ^5.0, run composer update eminos/statamic-group statamic/cms, then clear caches. Test any blueprint that uses groups in the CP after the upgrade, especially if you also upgraded Statamic major versions.

Gotchas and Tips

• Statamic 5 requires v2.1.0+. Earlier releases do not declare Statamic 5 support; Composer will either refuse the install or resolve an older Statamic version. Check composer why-not statamic/cms 5 if the upgrade is blocked.
• Groups do not create a nested data array by default. Nested field handles remain at their normal level in the entry data. Do not change front-end code to read seo.meta_title unless you have explicitly configured a nested data structure.
• Conditionals must reference the real field handles. If a field is visually inside a group, its handle is still the flat handle used elsewhere in the blueprint. Conditions based on the group handle itself will not behave like a data field.
• Blueprint cache and Stache. After editing blueprints or upgrading the addon, clear caches if the CP still shows the old layout. php please stache:clear and php artisan cache:clear resolve most “my group options are ignored” reports.
• Validation messages can look detached. Errors on nested fields appear against the nested field, not the group label. Use clear display names on nested fields so editors can find the failing input.
• Avoid relying on undocumented layout options. The group fieldtype is a small addon; pin the major version and re-check the README after minor releases. v2.1.0 itself is additive (Statamic 5 support) and does not introduce a documented breaking change.
• Test both fresh installs and upgrades. On a fresh Statamic 5 install, confirm the fieldtype is auto-discovered. On an upgrade from Statamic 4, confirm existing grouped blueprints still render and save without blueprint changes.
• Extension point: if the built-in group presentation is too limited, wrap it in a custom fieldset/partial or build a small custom fieldtype rather than patching vendor code. Keep vendor changes out of the repo so future compatibility releases remain painless.