Data Table - Selection

Data table can show a checkbox in each row, so the user can select several rows and act on them at once, for example to delete them.

Enable it with the selectable property.

When selection is on, each row gets a checkbox and a selection bar appears above the table. The checkbox in the header selects every row in items. If all rows are already selected, it unselects them.

While nothing is selected, the selection bar shows a hint. When rows are selected, it shows the number of selected rows, your buttons from the selection slot and a Clear selection button. The bar keeps its height in both states, so the table does not move when the first row is selected.

Selected rows are highlighted.

Example

Select a few heroes and click Delete.

HTML:

<DataTable #heroTable columns="$columns" items="$heroes" selectable (selectionChange)="onSelectionChange">
    <slotContent name="selection">
        <button type="button" class="btn btn-sm btn-outline-danger" (click)="removeSelected">Delete</button>
    </slotContent>
</DataTable>

PHP:

<?php

namespace ExamplesUi\Tables;

use ExamplesUi\HeroModel;
use Viewi\Components\BaseComponent;
use Viewi\UI\Components\Tables\DataTable;
use Viewi\UI\Components\Tables\TableColumn;

class TableSelectionExample extends BaseComponent
{
    public array $columns = [];
    public array $heroes = [];
    // keys (Id) of the selected rows
    public array $selected = [];
    public ?DataTable $heroTable = null;

    // ...

    public function onSelectionChange(array $keys)
    {
        $this->selected = $keys;
    }

    public function removeSelected()
    {
        $keys = $this->selected;
        $this->heroes = array_values(
            array_filter($this->heroes, fn(HeroModel $hero) => !in_array($hero->Id, $keys, true))
        );
        // the rows are gone, drop the selection with them
        $this->heroTable->clearSelection();
    }
}

Row Keys

The table identifies a row by one of its properties and keeps the selection as a list of these values. By default it uses Id. Set another property with selectKey:

<DataTable columns="$columns" items="$users" selectable selectKey="Email" (selectionChange)="onSelectionChange" />

The (selectionChange) event receives the list of keys of the selected rows. It is emitted on every change, including Clear selection.

Clearing the Selection

When you pass new rows in items yourself (after a delete, another page or a search), call clearSelection() on a table reference. Otherwise the old keys stay selected.

public ?DataTable $heroTable = null;

public function onPageChange(PaginationModel $paging)
{
    // ... load the rows of the new page
    $this->heroTable->clearSelection();
}

If you pass the rows through DataTableContext, the table clears the selection by itself each time it receives items.

Small Screens

With the stacked layout, the table header is hidden below 920px. The selection bar then shows its own select-all checkbox, and each row's checkbox sits at the top left of the row card.

Properties

selectable - (optional) shows the row checkboxes and the selection bar. Default: false.

selectKey - (optional) the item property that identifies a row. Default: Id.

selectionHint - (optional) the text in the selection bar while nothing is selected. Default: Select rows to act on several at once.

Events

(selectionChange) - (array $keys): void. Emitted when the selection changes, with the keys of the selected rows.

Methods

clearSelection() - unselects all rows.

Slots

selection - buttons for the selected rows, shown in the selection bar while at least one row is selected.