Livewire PowerGrid

Appearance

Table Columns ​

Defining Columns ​

After defining your DataSource Fields, return an array of Column definitions from columns(). Use Column::add() (chain title() and field()) or Column::make($title, $field, $dataField = ''). Then chain the configuration methods you need.

Add Column ​

phpapp/Livewire/ProductTable.php
use PowerComponents\LivewirePowerGrid\PowerGridComponent;
use PowerComponents\LivewirePowerGrid\Column;

class ProductTable extends PowerGridComponent
{
    public function columns(): array
    {
        return [
            Column::add()
                ->title('ID')
                ->field('id'),

            Column::add()
                ->title('Product name')
                ->field('name'),

            Column::add()
                ->title('Price')
                ->field('price'),
        ];
    }
}

Make Column ​

phpapp/Livewire/ProductTable.php
use PowerComponents\LivewirePowerGrid\PowerGridComponent;
use PowerComponents\LivewirePowerGrid\Column;

class ProductTable extends PowerGridComponent
{
    public function columns(): array
    {
        return [
            Column::make(title: 'ID', field: 'id'),

            Column::make(title: 'Product name', field: 'name'),

            Column::make(title: 'Price', field: 'price'),
        ];
    }
}

Defining Relationship-Based Columns ​

When using Database Relationships, pass $dataField so search, filters, and sorting hit the original database column. Available on both Column::add()->field() and Column::make().

This example creates a custom field kitchen_name from the kitchen relation, and sets dataField to kitchens.name.

phpapp/Livewire/ProductTable.php
use PowerComponents\LivewirePowerGrid\PowerGridComponent;
use PowerComponents\LivewirePowerGrid\PowerGridFields;
use PowerComponents\LivewirePowerGrid\Facades\PowerGrid;
use PowerComponents\LivewirePowerGrid\Column;
use App\Models\Product;

class ProductTable extends PowerGridComponent
{
    public function fields(): PowerGridFields
    {
        return PowerGrid::fields()
            ->add('id')
            ->add('name')
            ->add('kitchen_name', fn (Product $product) => e($product->kitchen->name));
    }

    public function columns(): array
    {
        return [
            Column::add()
                ->title('Kitchen Name')
                ->field(field: 'kitchen_name', dataField: 'kitchens.name'),
        ];
    }
}

Working With Custom Fields ​

Custom Fields transform values (formatting, calculations, combining columns). Pass $dataField so search, filters, and sorting use the mapped database column.

phpapp/Livewire/ProductTable.php
use PowerComponents\LivewirePowerGrid\PowerGridComponent;
use PowerComponents\LivewirePowerGrid\PowerGridFields;
use PowerComponents\LivewirePowerGrid\Facades\PowerGrid;
use PowerComponents\LivewirePowerGrid\Column;

class ProductTable extends PowerGridComponent
{
    public function fields(): PowerGridFields
    {
        return PowerGrid::fields()
            ->add('id')
            ->add('name')
            ->add('name_uppercase', fn ($product) => strtoupper(e($product->name)));
    }

    public function columns(): array
    {
        return [
            Column::make(
                    title: 'Product Uppercase',
                    field: 'name_uppercase',
                    dataField: 'products.name'
                ),
        ];
    }
}

Formatting Data in Columns ​

See Formatting Data.

Configuring Columns ​

[[sub-toc]]

Column Title ​

title() sets the header label. HTML is allowed (for example a font icon).

Parameters
(string) $title
phpapp/Livewire/ProductTable.php
use PowerComponents\LivewirePowerGrid\Column;

Column::add()
    ->title('Product Price'),
phpapp/Livewire/ProductTable.php
 Column::add()
    ->title('<i class="fas fa-low-vision" title="Visibility"></i>')

Column Field ​

field() links the column to a DataSource field.

ParameterDescription
(string) $fieldDataSource field
(string) $dataFieldDatabase table and field in dot notation (optional)
phpapp/Livewire/ProductTable.php
use PowerComponents\LivewirePowerGrid\Column;

Column::add()
    ->field('name'),

$dataField is required for joins and custom fields:

phpapp/Livewire/ProductTable.php
use PowerComponents\LivewirePowerGrid\Column;

Column::add()
    ->field('name', 'products.name'),

Column::add()
    ->field('category_name', 'categories.name'),

Column Placeholder ​

placeholder() sets the placeholder for the Filter input.

Parameter
(string) $placeholder
phpapp/Livewire/ProductTable.php
use PowerComponents\LivewirePowerGrid\Column;

Column::make('Product name', 'name')
    ->placeholder('Enter the name'),

Searchable Column ​

searchable() includes the column in the Search Input. See Searching Data.

phpapp/Livewire/ProductTable.php
use PowerComponents\LivewirePowerGrid\Column;

Column::make('Product name', 'name')
    ->searchable(),

Column::make('Kitchen', 'kitchen_name', 'kitchens.name')
    ->searchable(),

INFO

Pass $dataField for custom fields and joined relationships.

Raw Searchable Column ​

searchableRaw() searches with a RAW SQL LIKE expression. The ? binding is the table search term wrapped in %.

phpapp/Livewire/ProductTable.php
Column::make('Production date', 'produced_at_formatted', 'produced_at')
    ->searchableRaw('DATE_FORMAT(products.produced_at, "%d/%m/%Y") like ?'),

JSON Searchable Column ​

searchableJson($tableName) runs a case-insensitive LIKE on the column (useful for JSON text). Pass the table name, or '' to omit it.

phpapp/Livewire/ProductTable.php
Column::make('Additional', 'additional')
    ->searchableJson('products'),

Sortable Column ​

sortable() adds the sort control to the column header. See Sorting Data.

phpapp/Livewire/ProductTable.php
use PowerComponents\LivewirePowerGrid\Column;

Column::make('Product name', 'name')
    ->sortable(),

Column::make('Kitchen', 'kitchen_name', 'kitchens.name')
    ->sortable(),

INFO

Pass $dataField for custom fields and joined relationships.

Custom Sort ​

sortUsing() sets a sort callback and enables sorting. For Eloquent/Query Builder the callback receives the query and direction; for a Collection it receives the collection and direction, and must return the sorted collection.

phpapp/Livewire/ProductTable.php
use PowerComponents\LivewirePowerGrid\Column;

Column::make('Price', 'price')
    ->sortUsing(function ($query, string $direction) {
        $query->orderByRaw("price IS NULL, price {$direction}");
    }),

Natural Sort ​

naturalSort(true) sorts alphanumeric strings in natural order (img2 before img10). See Natural Sorting.

phpapp/Livewire/ProductTable.php
Column::make('Image', 'image')
    ->naturalSort(true),

Column Align ​

align() sets header and cell alignment. Accepted values: start, left, center, right, end. Default is left.

phpapp/Livewire/ProductTable.php
use PowerComponents\LivewirePowerGrid\Column;

Column::make('Price', 'price')
    ->align('end'),

Fixed On Responsive Mode ​

fixedOnResponsive() keeps the column visible in a Responsive Table.

phpapp/Livewire/ProductTable.php
use PowerComponents\LivewirePowerGrid\Column;

Column::make('Product name', 'name')
    ->fixedOnResponsive(),

Display Row Index ​

index() renders the row's 1-based position on the current page instead of the field value. Use a dedicated column:

phpapp/Livewire/ProductTable.php
use PowerComponents\LivewirePowerGrid\Column;

Column::add()
    ->index(),

Column::make('#', 'id')
    ->index(),

Hide Column ​

hidden() hides the column in the table view.

ParameterDescription
(bool) $isHiddenWhen true, hides the column from view but not from the Hide/Show toggle button
(bool) $isForceHiddenWhen true, removes the column from the Hide/Show toggle button

Both default to true. ->hidden() with no arguments hides the column and removes it from the toggle.

This example hides "Product Name" from the view, but the user can still show it from the toggle:

phpapp/Livewire/ProductTable.php
use PowerComponents\LivewirePowerGrid\Column;

Column::make('Product name', 'name')
    ->hidden(isHidden: true, isForceHidden: false),

This example also removes it from the toggle:

phpapp/Livewire/ProductTable.php
use PowerComponents\LivewirePowerGrid\Column;

Column::make('Product name', 'name')
    ->hidden(isHidden: true, isForceHidden: true),

Truncate and Tooltip ​

limit() truncates the displayed value, and tooltip() shows the full value on hover. Both come from the built-in TruncatePlugin.

MethodParametersDescription
limit()(int) $characters, (string) $end = '...'Truncate the displayed value
tooltip()(bool) $enabled = true, (string) $position = 'top'Show the full value in a tooltip
phpapp/Livewire/ProductTable.php
use PowerComponents\LivewirePowerGrid\Column;

Column::make('Description', 'description')
    ->limit(24)
    ->tooltip(),

Flux uses <flux:tooltip>. Other themes use a shared Alpine tooltip with a native title fallback. See Plugins.

Export Data Visibility ​

visibleInExport() controls whether the column is included when Exporting Data.

ParameterDescription
(bool) $visibletrue includes the column, false excludes it.

Hidden columns and Action Columns are excluded by default.

phpapp/Livewire/ProductTable.php
use PowerComponents\LivewirePowerGrid\Column;

Column::make('Product price', 'price')
    ->hidden()
    ->visibleInExport(true), // hidden in the grid, included in the file

Header Attribute Classes ​

headerAttribute() adds a class or style to the column header.

ParameterDescription
(string) $classAttrHTML class
(string) $styleAttrHTML style
phpapp/Livewire/ProductTable.php
use PowerComponents\LivewirePowerGrid\Column;

Column::make('Product name', 'name')
    ->headerAttribute('text-center', 'color:red')

Body Attribute Classes ​

bodyAttribute() adds a class or style to every cell in this column.

ParameterDescription
(string) $classAttrHTML class
(string) $styleAttrHTML style
phpapp/Livewire/ProductTable.php
use PowerComponents\LivewirePowerGrid\Column;

Column::make('Product name', 'name')
    ->bodyAttribute('text-center', 'color:red')

Content Class Field ​

contentClassField() uses the given DataSource field as the cell <span> class.

ParameterDescription
(string) $dataFieldDataSource field
phpapp/Livewire/ProductTable.php
use PowerComponents\LivewirePowerGrid\Column;

Column::make('Product name', 'name')
    ->contentClassField('status_class')

Content Classes ​

contentClasses() wraps the cell content in a <span> with the given CSS class.

When passing an array, PowerGrid matches the key against the column content and applies the corresponding class.

ParameterDescription
(array,string) $contentClassesColumn content => CSS class assignments
phpapp/Livewire/ProductTable.php
Column::make('Product name', 'name')
    ->contentClasses('text-blue-600');

Column::make('Product Availability', 'availability')
    ->contentClasses([
          'available'    => 'text-green-600',
          'out-of-stock' => 'text-red-600'
     ]);

Row Template ​

template() plus rowTemplates() interpolates a named HTML snippet on the server. Values are escaped; markup in the template is kept. This avoids rendering a Blade view per cell.

Return an array from the field closure: the key is the template name, the value is the placeholder map.

phpapp/Livewire/ProductTable.php
public function fields(): PowerGridFields
{
    return PowerGrid::fields()
        ->add('id')
        ->add('name', function ($row) {
            return [
                'template-name' => [ 
                    'id'   => $row->id, 
                    'name' => $row->name, 
                ], 
            ];
        });
}

public function columns(): array
{
    return [
        Column::make('ID', 'id')
            ->searchable()
            ->sortable(),

        Column::make('Name', 'name')
            ->template() 
            ->searchable()
            ->sortable(),
    ];
}

public function rowTemplates(): array
{ 
    return [ 
        'template-name' => '<div id="custom-{{ id }}" class="bg-red-100 py-1 rounded px-3">{{ name }}</div>', 
    ]; 
}

Placeholders use {{ key }}. Missing template names render nothing.

Edit On Click and Toggleable ​

editOnClick() and toggleable() are plugin macros. See Editing Data.

Show/Hide Columns ​

See Toggle Column Visibility for the header button. Use hidden() to hide a column in code, and Exclude Columns From Exporting to omit columns from export files.

Responsive Fixed Columns ​

With Responsive Layout, PowerGrid::responsive()->fixedColumns() replaces the default fixed list (id, checkbox, and actions). Pass every field you want to keep visible.

phpapp/Livewire/ProductTable.php
use PowerComponents\LivewirePowerGrid\PowerGridComponent;
use PowerComponents\LivewirePowerGrid\Facades\PowerGrid; 

class ProductTable extends PowerGridComponent
{
    public function setUp(): array
    {
        return [
            PowerGrid::responsive()
                ->fixedColumns('id', 'name', 'actions'),
        ];
    }
}

You can also mark a column with fixedOnResponsive().

Action Column ​

Column::action() is a dedicated column for Row Buttons. You can add it more than once and at any position. Action columns are omitted from exports unless you call visibleInExport(true).

phpapp/Livewire/ProductTable.php
use PowerComponents\LivewirePowerGrid\PowerGridComponent;
use PowerComponents\LivewirePowerGrid\Column;

class ProductTable extends PowerGridComponent
{
   public function columns(): array
    {
        return [
            Column::make('ID', 'id'),
            Column::make('Name', 'name'),
            Column::action('Action'), 
        ];
    }
}

Aggregating Data ​

Chain summarize('sum'|'count'|'avg'|'min'|'max', $label, header:, footer:) for built-in aggregates, or withSummary() for a custom closure. See Summarizing Data.

phpapp/Livewire/ProductTable.php
Column::make('Price', 'price')
    ->summarize('sum', 'Sum Price', header: true, footer: false),

Custom Macros ​

Register a Column macro in AppServiceProvider::boot() when you need extra query logic.

phpapp/Providers/AppServiceProvider.php
use PowerComponents\LivewirePowerGrid\Column;
use PowerComponents\LivewirePowerGrid\PowerGridComponent;

public function boot(): void
{
    Column::macro('searchableDateFormat', function () {
        $this->rawQueries[] = [
            'method'   => 'orWhereRaw',
            'sql'      => 'DATE_FORMAT('.$this->dataField.', "%d/%m/%Y") like ?',
            'bindings' => ['%{search}%'],
            'enabled'  => function (PowerGridComponent $component) {
                return filled($component->search);
            },
        ];

        return $this;
    });
}
phpapp/Livewire/ProductTable.php
 Column::make('Created At', 'created_at')
     ->searchableDateFormat(),
KeyDescription
methodQuery builder method, for example orWhereRaw.
sqlSQL passed to that method. {sortDirection} is replaced; other {placeholders} are left in SQL.
bindingsBound values. Closures receive the component. Strings may use {search} and other component properties.
enabledtrue or a closure. The query runs only when this is true.

Created By Luan Freitas and @DanSysAnalyst