LaraGrid

https://github.com/unnathianalytics/laragrid
Admin
LaraGrid is an Excel-style, keyboard-first datagrid library for Laravel and Livewire that offers...
Tokens:8,348
Snippets:98
Trust Score:6.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Configure Grid Focus Exits

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Demonstrates the standard setup for defining both tab-out navigation and completion-based focus movement.

```php
Grid::make('lines')
    ->editable()->rowsFrom('lines')->autoAppend()
    ->focusOutTo('[data-save]')        // operator tabs off the end → Save
    ->onCompleteFocus('[data-save]')   // operator picks "End of List" → lgrid:complete + Save
```

```php
    ->focusOutTo('#remarks')
    ->onCompleteFocus('[data-save]')
```

--------------------------------

### Install LaraGrid via Composer

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Run this command to add the package to your Laravel project.

```bash
composer require unnathianalytics/laragrid
```

--------------------------------

### Implementing Laragrid Server Hooks

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Examples of using onSelect for enrichment, afterCellChange for row consistency, and afterRowRemove for post-removal logic.

```php
// 1. Per-pick enrichment (SearchSelectColumn): the pick pre-fills dependent cells.
SearchSelectColumn::make('item_id')
    ->onSelect(function (RowContext $row, mixed $value): void {
        $item = Item::find($value);
        $row->set('rate', $item?->rate);
        $row->set('uom', $item?->uom);
    })

// 2. Grid-wide row consistency: runs after EVERY applied cell change (typing, paste,
//    fill-down). Example — derive nights from a date range:
->afterCellChange(function (RowContext $row, string $column): void {
    if (! in_array($column, ['fromDate', 'toDate'], true)) {
        return;
    }
    if ($row->get('fromDate') && $row->get('toDate')) {
        $nights = Carbon::parse($row->get('fromDate'))
            ->diffInDays(Carbon::parse($row->get('toDate')), false);
        $row->set('nights', $nights >= 1 ? (int) $nights : null);
    }
})

// 3. After a row removal — recompute host-side chrome (an "Allocated" total, a balance badge):
->afterRowRemove(fn () => $this->recomputeTotals())
```

--------------------------------

### Configure Keyboard Navigation Presets

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Set the navigation rhythm for the grid using keymap presets.

```php
->keymap('entry')
```

```php
->keymap('excel')
```

--------------------------------

### Define Grid Completion and Focus Behavior

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Configure conditions for grid completion and focus redirection upon completion.

```php
->completeWhenBalanced()
```

```php
->onCompleteFocus()
```

--------------------------------

### Binding and Initializing Grid Rows

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Use these methods to bind component data and initialize the grid with default rows.

```php
$this->rowsFrom('lines')
```

```php
$this->gridMountRows('lines')
```

```php
->defaultRows(n)
```

```php
->newRowUsing(fn () => [...])
```

--------------------------------

### Publish LaraGrid Assets and Config

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Use these commands to publish configuration, views, assets, or migrations as needed.

```bash
php artisan vendor:publish --tag=laragrid-config      # config/laragrid.php (global defaults)
php artisan vendor:publish --tag=laragrid-views       # blade views (mount + badge/edit-link cells)
php artisan vendor:publish --tag=laragrid-assets      # copy dist/ to public/vendor/laragrid
php artisan vendor:publish --tag=laragrid-migrations  # the saved-views table migration (auto-loads otherwise)
```

--------------------------------

### Configure Picker and Panel Interactions

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Define options for lookup lists and column-specific modal panels.

```php
->endOfListOption()
```

```php
->opensPanel('name')
```

--------------------------------

### Run Migrations for Saved Views

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Execute the migration to create the necessary table if using the saved views feature.

```bash
php artisan migrate
```

--------------------------------

### Configure Row Activation and Auto-Append

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Define row activation logic and automatic row creation behavior.

```php
->rowActivate()
```

```php
->autoAppend()
```

```php
->newRowUsing()
```

--------------------------------

### Test Grid Operations with Livewire

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Use this snippet to simulate grid operations and actions within a Livewire test environment.

```php
Livewire::test(BookingEntry::class)
    ->call('gridOps', 'lines', ['ops' => [
        ['t' => 'set', 'seq' => 1, 'row' => $key, 'col' => 'nights', 'v' => '3'],
    ]])
    ->call('gridAction', 'resorts', 'delete', [$id]);
```

--------------------------------

### Configure Grid Export Options

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Enable export functionality on a grid definition using the exportable method.

```php
Grid::make('resorts')
    ->query(fn () => Resort::query())
    ->authorize('resort.viewAny')
    ->exportable()                                    // csv + xlsx + pdf (the config default set)
    // ->exportable(['csv', 'xlsx'])                  // or exactly these formats
    // ->exportable(['csv'], fileName: 'resorts', limit: 10000)
```

--------------------------------

### Enable Query and Width Persistence

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Apply persistence methods to a grid definition to maintain search, filter, sort, and column width states.

```php
Grid::make('items')
    ->query(fn () => Item::query())
    ->authorize('item.viewAny')
    ->persistQuery()                  // opt-in; ->persistQuery('session', 'key') overrides the key
    ->persistWidths()                 // composes — different lifetime, different state
```

--------------------------------

### Define Grid Actions

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Configure per-row, bulk, and toolbar actions using the fluent API. Actions are fail-closed and re-authorized on the server before execution.

```php
->actions([          // per-row buttons in a trailing column
    Action::make('edit')->icon('✎')->url(fn ($row) => route('items.edit', $row['id'])),
    Action::make('archive')->confirm('Archive?')->visible(fn ($row) => ! $row['archived'])
        ->call(fn (array $row) => Item::whereKey($row['id'])->archive()),
])
->bulkActions([      // run over checked rows; a selector gutter + toolbar bulk bar appear
    Action::make('delete')->confirm('Delete selected?')
        ->call(fn (array $keys) => Item::whereKey($keys)->delete()),
])
->toolbarActions([   // grid-scoped buttons in the toolbar
    Action::make('new')->label('New Item')->url(fn () => route('items.create')),
])
```

--------------------------------

### Configure app-wide theme default

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Sets the default theme for all grids in the application via the configuration file.

```php
// config/laragrid.php — app-wide default; any grid's ->theme() overrides it
'theme' => 'emerald',
```

--------------------------------

### Implement an Editable Entry Grid

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Define a Livewire component using the WithLaraGrid trait to manage an editable grid with custom columns, validation, and persistence logic.

```php
use LaraGrid\Columns\{SerialColumn, SearchSelectColumn, IntegerColumn, DecimalColumn, FormulaColumn, TextColumn};
use LaraGrid\Editing\RowContext;

class BookingEntry extends Component
{
    use WithLaraGrid;

    /** @var list<array<string, mixed>> */
    public array $lines = [];

    public function mount(): void
    {
        $this->lines = $this->gridMountRows('lines');   // seeds defaultRows via the factory
    }

    protected function grids(): array
    {
        return ['lines' => Grid::make('lines')
            ->editable()
            ->rowsFrom('lines')                         // binds public array $lines
            ->authorize(fn () => $this->authorize('booking.create'))
            ->defaultRows(3)
            ->newRowUsing(fn () => ['nights' => 1])     // template for seeded AND inserted rows
            ->minRows(1)
            ->autoAppend()                              // Enter past the last cell grows the grid
            ->focusOnMount()
            ->focusOutTo('[data-save]')                 // Tab past the last cell lands on Save
            ->columns([
                SerialColumn::make(),
                SearchSelectColumn::make('resort_id')->label('Resort')
                    ->optionsUsing(fn (string $term) => Resort::query()
                        ->when($term !== '', fn ($q) => $q->where('name', 'like', "%{$term}%"))
                        ->limit(50)->get(['id', 'name'])
                        ->map(fn ($r) => ['value' => (string) $r->id, 'label' => $r->name])
                        ->all())
                    ->onSelect(function (RowContext $row, mixed $value): void {
                        // Enrichment: the pick pre-fills the rate; write-backs reconcile
                        // into the client row automatically.
                        $row->set('rate', Resort::whereKey($value)->value('comparison_tariff'));
                    })
                    ->required()->minChars(0)->debounce(250)->grow(),
                IntegerColumn::make('nights')->rules(['integer', 'min:1'])->required()->width(90),
                DecimalColumn::make('rate')->scale(2)->rules(['numeric', 'min:0'])->width(120),
                FormulaColumn::make('amount')->formula('round(nights * rate, 2)')->width(130),
                TextColumn::make('note')->maxLength(100)->grow(),
            ])
            ->footer([Aggregate::sum('amount')->format('number', ['scale' => 2])])];
    }

    public function save(): void
    {
        $rows = $this->gridRows('lines');       // cleaned: blank trailing rows + bookkeeping stripped

        Booking::createFromLines($rows);        // your persistence — the grid never owns it

        $this->lines = $this->gridMountRows('lines');
        $this->reseedGrid('lines');             // required after any out-of-band rows change
    }
}
```

--------------------------------

### Configure Column Focus Modes

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Defines how keyboard navigation interacts with specific columns using FocusMode enums and default value callbacks.

```php
use LaraGrid\Columns\FocusMode;

// Variable (Default): Always receives sequential keyboard focus
TextColumn::make('party_name')
    ->focusMode(FocusMode::Always);

// Semi-Variable: Skipped on keyboard navigation (Tab/Enter), focusable and editable on mouse click
DecimalColumn::make('qty')
    ->focusMode(FocusMode::Manual, default: 1);

// Fixed: Skipped on keyboard navigation, read-only / non-editable, dynamic Closure default
DateColumn::make('vch_date')
    ->focusMode(FocusMode::Never, default: fn () => now()->format('Y-m-d'));
```

--------------------------------

### Apply a theme to a grid

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Sets a specific color scheme for an individual grid instance.

```php
Grid::make('items')->theme('blue')        // per grid (unknown names fail loud at build time)
```

--------------------------------

### Persist Column Widths

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Enable memory for column layout adjustments.

```php
->persistWidths()
```

--------------------------------

### Registering JavaScript UI Extensions via Pending Queue

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Use the window.LaraGrid.pending queue to register painters, editors, and formatters to ensure they are processed before the grid initializes.

```javascript
// The JS twins and custom UI register through window.LaraGrid — via the ORDER-INDEPENDENT
// `pending` queue, which works from any script position, before or after the grid bundle:
(window.LaraGrid = window.LaraGrid || {}).pending = [
    (LG) => {
        LG.registerPainter('rating', (cellEl, ctx) => { /* draw the cell */ });
        LG.registerEditor('rating', RatingEditor);        // { mount, value, focus, destroy }
        LG.registerFormatter('inr', (value, args) => …);  // twin of the PHP formatter
        LG.registerCast('paise', { parse, editText });    // twin of the PHP cast
    },
];
```

--------------------------------

### Registering Custom PHP Columns and Formatters

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Define custom column classes and register formatters or casts within a service provider.

```php
// A custom column type is just a class:
class RatingColumn extends \LaraGrid\Columns\Column
{
    public function painterId(): string { return 'rating'; }
    public function editorId(): ?string { return 'rating'; }
    public function parseSpec(): array { return ['kind' => 'int']; }
}

// App-specific formatters and parse kinds register in a service provider:
app(\LaraGrid\Formatting\FormatRegistry::class)->register('inr', new InrFormatter);
app(\LaraGrid\Casting\CastRegistry::class)->register('paise', new PaiseCast);
```

--------------------------------

### Define a LaraGrid Component

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Implement the WithLaraGrid trait in your Livewire component and define the grid configuration within the grids method.

```php
use App\\,Models\\Resort;
use LaraGrid\\Actions\\Action;
use LaraGrid\\Aggregate;
use LaraGrid\\Columns\\{SerialColumn, TextColumn, IntegerColumn, DateColumn, ComputedColumn};
use LaraGrid\\Filters\\SelectFilter;
use LaraGrid\\Grid;
use LaraGrid\\Livewire\\WithLaraGrid;
use LaraGrid\\Support\\CellHtml;
use Livewire\\Component;

class ResortsIndex extends Component
{
    use WithLaraGrid;   // ← required: provides gridDefinition() and the grid RPCs

    protected function grids(): array
    {
        return ['resorts' => Grid::make('resorts')
            ->query(fn () => Resort::query())
            ->authorize('resort.viewAny')            // mandatory — grids are fail-closed
            ->paginate(25, [10, 25, 50, 100])
            ->defaultSort('name')
            ->searchable(['name', 'shortcode', 'resorts.slug'])   // see note below
            ->filters([
                SelectFilter::make('type')->label('Type')
                    ->options(fn () => Resort::distinct()->orderBy('type')->pluck('type', 'type')),
                SelectFilter::make('visibility')->label('Visibility')
                    ->options(['show' => 'Show', 'hide' => 'Hide']),
            ])
            ->columns([
                SerialColumn::make(),
                TextColumn::make('name')->label('Resort')->sortable()->searchable()->grow(),
                TextColumn::make('type')->sortable()->width(120),
                IntegerColumn::make('hits')->sortable()->width(90),
                ComputedColumn::make('status')->html()->width(90)
                    ->state(fn (array $row) => $row['visibility'] === 'show'
                        ? CellHtml::badge('green', 'Show')
                        : CellHtml::badge('zinc', 'Hide')),
                DateColumn::make('created_at')->label('Added')->sortable()->width(110),
            ])
            ->footer([Aggregate::sum('hits')->format('number')])
            ->exportable(['csv', 'xlsx', 'pdf'])     // toolbar Export control — see Exports
            ->actions([
                Action::make('edit')->icon('✎')->url(fn ($row) => route('resorts.edit', $row['id'])),
                Action::make('delete')->icon('✕')->confirm('Delete this resort?')
                    ->call(fn (array $row) => Resort::whereKey($row['id'])->delete()),
            ])
            ->stickyHeader()->striped()->maxHeight('70vh')];
    }

    public function render()
    {
        return view('livewire.resorts-index');
    }
}
```

--------------------------------

### Configure picker exit with endOfListOption

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Adds a synthetic option to a picker column to signal completion when selected on a trailing row.

```php
SearchSelectColumn::make('item_id')
    ->endOfListOption()                                  // default label: <-- End of List -->
    // ->endOfListOption('— Done adding lines —')        // custom label
    // ->endOfListOption(allowOnEmpty: true)             // offer it even on an empty grid
```

--------------------------------

### Listen for grid completion events

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Handles the lgrid:complete DOM event to perform custom actions like opening dialogs or scrolling.

```js
document.addEventListener('lgrid:complete', (e) => {
    if (e.detail.grid === 'lines') { /* open a confirm dialog, scroll a summary… */ }
});
```

--------------------------------

### Scope Persistence Key

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Use a custom key to isolate grid state, useful for multi-tenant applications.

```php
->persistQuery(key: "items:{$companyId}")
```

--------------------------------

### Managing Grid State

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Methods for handling row validation, constraints, and state synchronization.

```php
->minRows(n)
```

```php
gridRows()
```

```php
$this->reseedGrid('lines')
```

--------------------------------

### Define a custom theme class

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Defines custom CSS properties to create a unique theme accent.

```css
.lgrid--theme-brand { --lgrid-theme-accent: #0f766e; --lgrid-theme-accent-dark: #2dd4bf; }
```

--------------------------------

### Register Custom Exporters

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Add custom export formats by registering new exporter classes in a service provider.

```php
// A service provider:
app(\LaraGrid\Export\ExporterRegistry::class)->register('pdf', new BrandedDompdfExporter);
app(\LaraGrid\Export\ExporterRegistry::class)->register('ods', new OdsExporter);

// A grid:
->exportable(['csv', 'ods'])     // unknown names still fail loudly at build time
```

--------------------------------

### Column Focus Modes

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Configures how keyboard navigation (Tab/Enter) interacts with specific columns using the focusMode method.

```APIDOC
## Method: ->focusMode()

### Description
Controls the keyboard navigation behavior for a column, allowing for fixed, semi-variable, or variable focus patterns.

### Parameters
- **mode** (FocusMode|string) - Required - The focus mode (Always, Manual, or Never).
- **default** (mixed|Closure) - Optional - A static value or callback to provide a default value for new rows.

### Usage Example
use LaraGrid\Columns\FocusMode;

// Variable (Default): Always receives sequential keyboard focus
TextColumn::make('party_name')
    ->focusMode(FocusMode::Always);

// Semi-Variable: Skipped on keyboard navigation, editable on mouse click
DecimalColumn::make('qty')
    ->focusMode(FocusMode::Manual, default: 1);

// Fixed: Skipped on keyboard navigation, read-only
DateColumn::make('vch_date')
    ->focusMode(FocusMode::Never, default: fn () => now()->format('Y-m-d'));
```

--------------------------------

### Display-only Grid Component

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Renders a grid in display-only mode without requiring a Livewire component. This mode supports full keyboard navigation, selection, and column features.

```APIDOC
## Blade Component: <x-laragrid>

### Description
Displays a grid with provided data rows. This mode is intended for read-only or client-side managed data where no Livewire backend is required.

### Parameters
- **grid** (mixed) - Required - The grid configuration object.
- **rows** (array) - Required - An array of associative arrays representing the grid data.

### Usage Example
<x-laragrid :grid="$grid" :rows="[['name' => 'Alpha'], ['name' => 'Beta']]" />
```

--------------------------------

### Render LaraGrid in Blade

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Use the x-laragrid component to render the grid defined in your Livewire component.

```blade
<x-laragrid :grid="$this->gridDefinition('resorts')" />
```

--------------------------------

### Display-only Grid Component

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Renders a grid without requiring a Livewire component or query builder, suitable for static data display.

```blade
<x-laragrid :grid="$grid" :rows="[['name' => 'Alpha'], ['name' => 'Beta']]" />
```

--------------------------------

### Trigger Export via JavaScript

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Manually trigger a grid export event from the frontend using a CustomEvent.

```javascript
el.dispatchEvent(new CustomEvent('lgrid:toolbar', {
    bubbles: true, detail: { grid: 'resorts', kind: 'export', value: 'xlsx' },
}));
```

--------------------------------

### Enable Saved Views in Laragrid

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Add the savedViews method to your grid definition to enable the server-persisted views feature.

```php
Grid::make('resorts')
    ->query(fn () => Resort::query())
    ->authorize('resort.viewAny')
    ->savedViews()                    // opt-in; ->savedViews('key') overrides the storage key
```

--------------------------------

### Clear Grid Query State

Source: https://github.com/unnathianalytics/laragrid/blob/main/README.md

Manually remove stored query state for a specific grid identifier.

```php
$this->forgetGridQuery('items');      // no-op on a grid without ->persistQuery()
```
Tokens:
Raw