Columns

To display your records you need to add columns to your table. You can specify what field to display - including relationships. It is also possible to search and sort these columns if you choose to. There is also a variety of different column types to make searching work out of the box.

Columns can be registered in the columns method of your Livewire Table.

protected function columns(): array
{
    return [
        //
    ];
}

Column Types

Currently, there are 6 different column types available.

Column

The Column is the generic column type for most use cases. This column type is primarily meant for text like a name or email address.

Column::make(__('Name'), 'name'),

Boolean Column

Booleans can be displayed using the BooleanColumn. This column will render a circle to display the current state.

BooleanColumn::make(__('Published'), 'published'),

Date Column

If you are working with dates, a DateColumn should be used. You can also supply a format using the format method.

DateColumn::make(__('Created At'), 'created_at')
    ->format('d m Y'),

Select Column

When a column can only accept a list of values, you may be interested in the SelectColumn. With this column you can specify the options that can be used. If the field is searchable, you will get a dropdown of options to choose from.

SelectColumn::make(__('Favorite Fruit'), 'favorite_fruit')
    ->options([
        'Apple' => 'Apple',
        'Banana' => 'Banana',
        'Pear' => 'Pear',
    ]),

You can also use a nested array in order to make use of option groups. Note that only one level of nesting is supported.

SelectColumn::make(__('Favorite Fruit'), 'favorite_fruit')
    ->options([
        'Red Fruit' => [
            'Apple' => 'Apple',
            'Strawberry' => 'Strawberry',
        ],
        'Yellow Fruit' => [
            'Banana' => 'Banana',
        ],
        'Green Fruit' => [
            'Pear' => 'Pear',
        ],
    ]),

Image Column

Images can easily be displayed using the ImageColumn. The value of the field will be the src of the image. It is also possible to ajust the size of the image by using the size method or the width and height methods individually.

By default, the width and height of images are 32 pixels.

ImageColumn::make(__('Thumbnail'), 'thumbnail')
    ->size(75, 75),

ImageColumn::make(__('Banner'), 'banner')
    ->width(100)
    ->height(50),

Image columns will disable the title of the column to preserve space. It can be enabled back using the header method. See the header section for more information.

View Column

Although columns have an option to display their values as HTML, having a lot of markup in your column can be a bit messy.

With a ViewColumn you can reference a view to load as the second argument.

INFO

The model will be passed to the view.

ViewColumn::make(__('Actions'), 'actions'),

If you're containing links in your view, it may be helpful to disable the column from being clicked. See links for more information about this.

ViewColumn::make(__('Actions'), 'actions')
    ->clickable(false),

By default, only the model will be passed to the view. Any additional data can be passed by using the with method.

ViewColumn::make(__('Actions'), 'actions')
    ->with([
        'key' => 'value',
    ]),

// or

ViewColumn::make(__('Actions'), 'actions')
    ->with('key', 'value'),

Just like any other column, the header can be disabled as well.

JSON

Data can also be accessed from a JSON column.

Column::make(__('Color'), 'settings->color'),

Searchable

To quickly find the records you need, you can make your columns searchable. By default, searching is not enabled for any column, but it can easily be enabled.

Column::make(__('Name'), 'name')
    ->searchable(),

It is also possible to pass a callback in order to handle searching yourself.

use Illuminate\Database\Eloquent\Builder;

Column::make(__('Name'), 'name')
    ->searchable(function (Builder $builder, mixed $search): void {
        //
    }),

Sortable

Records can be sorted by clicking on the title of the column. Just like searching, sorting is not enabled by default.

Column::make(__('Name'), 'name')
    ->sortable(),

To set the default sort column and direction, use the $sortColumn and $sortDirection properties of your table.

public string $sortColumn = 'name';

public string $sortDirection = 'asc';

You can also handle sorting yourself by passing a callback.

use Illuminate\Database\Eloquent\Builder;
use RamonRietdijk\LivewireTables\Enums\Direction;

Column::make(__('Name'), 'name')
    ->sortable(function (Builder $builder, Direction $direction): void {
        //
    }),

Visibility

All columns are visible in the table by default. It is possible to hide columns by calling the hide method. In that case, they will only be shown when they are enabled via the dropdown.

Column::make(__('Name'), 'name')
    ->hide(),

Relations

If you wish to show data from a related model, you can prefix the column with the name of the relations. Always use the name of the relations and not of the tables.

Column::make(__('Company'), 'author.company.name'),

You can also use relations with a cardinality greater than one. The values will automatically be joined with a comma.

Column::make(__('Tags'), 'tags.name'),

Head to relations to know more about relations and how they work behind the scenes.

Display Using

Sometimes you wish to format the data in your table differently from how it's saved in the database. Luckily, this is easily done using the method displayUsing on your column.

INFO

This will work for any column and always takes priority over a format.

Column::make(__('Name'), 'name')
    ->displayUsing(function (mixed $value, Model $model): string {
        return ucfirst($value);
    }),

Computed

In some cases you wish to display values which aren't stored in the database but are rather calculated like the aggregate function COUNT(*). This can be the total amount of blogs written by a user, for example.

If you pass a callback as the second argument to a column, it will mark the column as computed. The callback is the same as displayUsing, documented above.

INFO

Computed columns can't be searched or sorted unless you have supplied a callback.

WARNING

In the example below the column will calculate the amount of blogs for each user individually, introducing the N+1 problem. This can easily be overcome to keep the table efficient. Please see efficiency to see the best practices.

Column::make(__('Total Blogs'), function (mixed $value, Model $model): int {
    return $model->author->blogs()->count();
}),

You can also manually mark a column as computed.

Column::make(__('Name'), 'name')
    ->computed(),

Header

Sometimes, displaying the title of the column in the header is not required. It can preserve space when showing a thumbnail, for example.

Luckily, this is easily done by using the header method. If false is passed as the first argument, the header will not be rendered in the table. The title of the column will always be visible in the column selection.

Column::make(__('Name'), 'name')
    ->header(false),

Footer

To display information in the footer of the column, you can use the footer method. Pass a callback to this method and the contents will be rendered on the table.

The content in the footer will not be escaped in the table.

Column::make(__('Name'), 'name')
    ->footer(function (): string {
        return "Where there's a will, there's a way";
    }),

As HTML

WARNING

Always be cautious when using asHtml() as this may introduce XSS vulnerabilities.

You can also choose to render the content of the column directly without any escaping.

Column::make(__('Badge'), function (mixed $value, Model $model): string {
    return '<div>...</div>';
})->asHtml(),