Data Table - Search

Data table supports searching.

Enable it with the search property and handle the (search) event. The table does not filter the items for you. Your handler decides which items to pass back in items, so the search can run in memory or on the server.

(search) - (string $search): void

The search box waits until the user stops typing for 300 ms before it emits (search). Clearing the box with its clear button or the Escape key emits the event right away with an empty string.

Each search also moves the pager back to page 1.

Example

<DataTable columns="$columns" items="$items" search (search)="onSearch" />

<?php

namespace ExamplesUi\Tables;

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

class FormsExample extends BaseComponent
{
    public array $columns = [];
    // all items
    public array $items = [];
    // items for the table
    public array $filtered = [];

    public function init()
    {
        $this->setUpColumns();
        $this->prepareHeroes();        
    }

    public function setUpColumns()
    {
        // Columns definition
        $this->columns = [
            new TableColumn('Id'),
            new TableColumn('Name'),
        ];        
    }

    public function prepareHeroes()
    {
        // let's pretend that we got these from some API
        $hero = new HeroModel();
        $hero->Id = 1;
        $hero->Name = 'Superman';
        $this->items[] = $hero;

        $hero = new HeroModel();
        $hero->Id = 2;
        $hero->Name = 'Batman';
        $this->items[] = $hero;

        $hero = new HeroModel();
        $hero->Id = 3;
        $hero->Name = 'Wonder Woman';
        $this->items[] = $hero;

        // display all items by default
        $this->filtered = $this->items;
    }

    // handle table search event
    public function onSearch(string $filter)
    {
        $searchText = strtolower($filter);
        $this->filtered = array_filter(
            $this->items,
            fn(HeroModel $hero) => !$filter
                || strpos(
                    strtolower($hero->Name),
                    $searchText
                ) !== false
        );
    }
}

The result:

Nothing Found

If the search is not empty and items is empty, the table shows a "No matches" message with a Clear search button. The button empties the search box and emits (search) with an empty string. Type a name that does not exist in the example above to see it.

Read more in Empty States.

Initial Search Text

Use the searchValue property to put text into the search box, for example a search term restored from the URL.

<DataTable columns="$columns" items="$filtered" search searchValue="$term" (search)="onSearch" />

searchValue only fills the box. It does not emit (search), so pass items that are already filtered by the same term.

Using DataTableContext

DataTable looks for a DataTableContext instance in its parent component. It is useful when you build your own list component that wraps a DataTable and wants to set its properties and listen to its events from code.

Inject the context with Scope::COMPONENT in the wrapper component, pass properties with passProps, and register event handlers with on:

<?php

namespace Components\Views\Heroes;

use Viewi\Components\BaseComponent;
use Viewi\DI\Inject;
use Viewi\DI\Scope;
use Viewi\UI\Components\Tables\DataTableContext;
use Viewi\UI\Components\Tables\TableColumn;

class HeroList extends BaseComponent
{
    public function __construct(
        #[Inject(Scope::COMPONENT)]
        private DataTableContext $tableContext
    ) {}

    public function init()
    {
        $this->tableContext->on('search', fn(string $text) => $this->load($text));
        $this->load('');
    }

    public function load(string $text)
    {
        // load the heroes that match $text, for example from an API
        $heroes = [];
        $this->tableContext->passProps([
            'columns' => [new TableColumn('Id'), new TableColumn('Name')],
            'items' => $heroes,
            'search' => true,
            'searchValue' => $text,
        ]);
    }
}

<DataTable />

Properties you can pass with passProps: id, classList, items, columns, search, searchValue, paging, add, remove, edit, filter, addText, editInline, editItem, changeMode. Other keys are ignored. A null value is ignored as well.

Passing items also clears the row selection.

Events forwarded to the context: search, page, pageSize, create, edit, delete, save, cancel. The context keeps one handler per event name, so a second on call for the same event replaces the first one.

Properties

search - (optional) shows the search box. Default: false.

searchValue - (optional) the text in the search box. Default: ''.

Events

(search) - (string $search): void. Emitted when the search text changes.