Nova Gridder Laravel Package

Getting Started

Confirm compatibility before you composer require. The package targets Laravel Nova and was last tagged in mid-2021, so check the composer.json constraint against your installed Nova major (nova/laravel/nova). On a Nova 4/5 app you should treat this as a "vendor and verify" step, not a drop-in.

composer require demency/nova-gridder

After install, look at three things in the repo before writing any layout code:

1. README.md — the canonical usage example. With 17 stars and one release, this is the documentation.
2. src/ — the field class(es) exposed (the namespace is Demency\NovaGridder) and their fluent setters. The public methods are the real API.
3. resources/js/components/ — the Vue component that renders the grid. This tells you exactly which Tailwind grid utilities are honoured and how responsiveness is wired.

First use case: take a Resource detail view that currently stacks 8–12 fields vertically and lay them out as a responsive grid on the details page.

use Demency\NovaGridder\NovaGridder;

public function fields(NovaRequest $request)
{
    return [
        NovaGridder::make()
            ->fields([
                ID::make()->sortable(),
                Text::make('Name'),
                Text::make('Email'),
                Text::make('Company'),
            ]),
    ];
}

Start with a small, read-only resource (a "show" page you rarely edit), verify rendering, then roll it out to resources with more complex field mixes. Do not start with a resource that uses custom Field subclasses or file uploads — get the layout mechanics working on plain fields first.

Implementation Patterns

Wrap only the detail-relevant fields. The grid is a layout container; fields you want on index/forms should stay in the normal fields() array. A common pattern is to keep the flat fields used by forms/index and add the grid container for the detail context, or split the array based on $request->isResourceDetailRequest() (or the equivalent isDetail()/isForm() helpers your Nova version provides).

Responsive column strategy. Because the package is built on Tailwind's grid, express the layout as a mobile-first scale and let the component/your config map it to sm:/md:/lg:/xl: breakpoints. A practical default for Nova detail pages is one column on mobile, two at md, three at xl. Keep the total number of columns in sync with any span/offset values you assign.

Span wide fields. Text-heavy fields (description, notes, JSON, code) usually want to span multiple columns while scalars sit one-per-cell. Use whatever span/width setter the field exposes (check src/ — many grid packages on Nova use ->span(), ->colSpan(), or a Tailwind class string). If spans aren't available, restructure with multiple grid rows instead of fighting the API.

Extract layouts for reuse. Don't repeat grid definitions in every resource. Put the layout in a trait or abstract resource:

trait HasDetailLayout
{
    protected function detailGrid(): NovaGridder
    {
        return NovaGridder::make()->fields([
            $this->identityFields(),
            $this->contactFields(),
            $this->auditFields(),
        ]);
    }
}

Fields are still plain Laravel\Nova\Fields\Field instances, so ->canSee(), ->hideWhenCreating(), ->readonly(), and the rest continue to work inside the grid.

Group by meaning, not by column count. The temptation is to arrange fields so the grid "looks right." Arrange by domain instead — identity, contact, metadata — and accept some asymmetry. Grids that mirror the data model survive refactors; grids tuned to a screenshot don't.

Conditional layout per request. Layout can legitimately vary by user role. Wrap the grid construction in a Gate::allows()/policy check and return either the grid or a plain field array. Keep this logic in the resource, not in the field container — it's easier to test.

Pair with Panel sparingly. If your Nova version supports Panel, a panel containing a gridder (or a gridder containing panels) gets visually noisy fast. Pick one level of nesting: panels for section headings, grid for the fields inside a panel.

Gotchas and Tips

• Detail-only scope. The package targets Resource Details. Don't expect index table columns or form layouts to change. If you need form layout control too, that's a separate concern and often a different package.
• Hidden fields collapse cells. canSee() returning false means the field isn't rendered, so a grid row can end up with fewer cells than columns. Design for graceful fallback (e.g. don't hard-code a single field into a 4-column row and assume it fills the width).
• Tailwind purge is the classic failure mode. If you write arbitrary Tailwind classes in your own layout config, they may be purged from Nova's compiled CSS because the scanner doesn't see them in Nova's source. Prefer the classes the package ships with, or add your custom classes to the package's own entry point after publishing assets.
• Verify the Nova version constraint. Mid-2021 is Nova 3-era. On Nova 4/5, field component contracts changed (Form/Detail split, Vue 3, etc.). A clean composer update isn't proof it renders — actually open the detail page.
• Asset publishing. After vendor:publish, re-run npm run prod (or npm run dev) so the Vue component is compiled into public/vendor/.... A silent 404 for the JS chunk shows as an empty or broken panel with no obvious error.
• Debug order: browser console → network tab for the vendor JS → Vue Devtools to confirm the component mounted with props → src/ to see how props are populated server-side. Most "it does nothing" reports are a missing asset publish, not a layout bug.
• Column math. Rows that exceed the configured column count silently wrap. If a field unexpectedly drops to the next line, the spans sum past the total — that's the bug, not a CSS problem.
• Extension points. The cleanest customisation is usually (a) subclassing the field and overriding the component, or (b) keeping the grid simple and adding a custom Field with its own Vue component for the one-off widget. Don't fork the package for a single layout tweak — vendor it locally (composer.json path repository) first if you must.
• Maintenance assessment. Given the low star count and single release, budget for reading the source whenever something breaks and consider it a "read-only layout convenience" rather than infrastructure. If your admin UI is mission-critical, evaluate whether Nova's built-in Panel/Field grouping, or a more actively maintained grid package, covers the same need with less vendor risk.