Icons

The widgets name every icon they draw with a semantic key, such as search.icon for the search field or callout.info for an info callout, and an icon pack maps each key to icon classes. To change the library's icons, override a few keys or switch the whole pack, and every widget follows with no change to its views.

Your own views don't need any of this: write icon markup with the classes directly, such as <i class="ph ph-rocket-launch"></i>. Where a library component takes an icon argument, pass the classes the same way.

Overriding keys

Ui::extendIcons() replaces keys in every pack. It takes an array, which applies to every pack alike, or a closure that receives each pack's icons and name and returns the icons to use. The demo page swaps the info callout's icon and the search field's icon with an array, then gives the bootstrap pack its own glyphs for them with a closure, and the callout and search field below pick up the new icons:

{{ Ui::callout(label: 'Heads up', comment: 'The info callout draws callout.info, which this page overrides.') }}

{{ Ui::searchInput(name: 'icon_search', placeholder: 'The search field draws search.icon') }}

<?php

namespace App\Controllers\Reference\ExtendingController;

use Larajax\Ui\Classes\Icons\PhosphorIconPack;
use Larajax\Ui\Facades\Ui;

/**
 * IconRegistrations changes some of the icons the library draws for the Icons page, which an app does once in a service provider instead.
 */
trait IconRegistrations
{
    /**
     * registerExampleIcons registers an amber pack on top of the phosphor pack, then overrides two keys the widgets use in every pack.
     */
    protected function registerExampleIcons(): void
    {
        Ui::registerIconPack('amber', function (): array {
            return array_replace((new PhosphorIconPack)->icons(), [
                'action.delete' => 'ph ph-trash-simple',
            ]);
        });

        Ui::extendIcons([
            'callout.info' => 'ph ph-lightbulb',
            'search.icon' => 'ph ph-binoculars',
        ]);

        Ui::extendIcons(function (array $icons, string $pack): array {
            if ($pack !== 'bootstrap') {
                return $icons;
            }

            return array_replace($icons, [
                'callout.info' => 'bi bi-lightbulb',
                'search.icon' => 'bi bi-binoculars',
            ]);
        });
    }
}

The demo page registers these in its action, so they apply to that page only. An app overrides its icons once, in a service provider's boot() method. Extensions apply after the pack and the configured overrides, in the order they were added.

Icon packs

The library ships three packs: phosphor (Phosphor Icons, the default), bootstrap (Bootstrap Icons) and october, each mapping every key. A pack only maps keys to classes, so load the icon font itself in your layout.

To switch the pack every widget uses, set LARAJAX_ICONS in your .env file, such as LARAJAX_ICONS=bootstrap.

Ui::registerIconPack() adds a pack, or replaces one, by name. The pack is an array of keys and classes, a class that implements Larajax\Ui\Classes\IconPack (or its name), or a closure that returns the array. A closure or class name is only resolved when the pack is first used. The registrations above add an amber pack built on the phosphor pack with one key swapped. The table compares a few keys across the packs:

@php
    $iconManager = app(\Larajax\Ui\Classes\IconManager::class);
@endphp

<table class="table ui-icon-table">
    <thead>
        <tr>
            <th>
                Key
            </th>
            @foreach (['phosphor', 'bootstrap', 'amber'] as $iconPack)
                <th>
                    {{ $iconPack }}
                </th>
            @endforeach
        </tr>
    </thead>
    <tbody>
        @foreach (['action.delete', 'datepicker.date', 'pagination.next', 'repeater.add'] as $iconKey)
            <tr>
                <td>
                    <code>
                        {{ $iconKey }}
                    </code>
                </td>
                @foreach (['phosphor', 'bootstrap', 'amber'] as $iconPack)
                    <td>
                        <i class="{{ $iconManager->icons($iconPack)[$iconKey] }}" aria-hidden="true"></i>
                    </td>
                @endforeach
            </tr>
        @endforeach
    </tbody>
</table>

The keys the library uses

The demo page lists every key of the default pack with its icon, from the icon manager's icons() method, which returns a pack's resolved keys and classes:

<div class="ui-icon-grid">
    @foreach (app(\Larajax\Ui\Classes\IconManager::class)->icons() as $iconKey => $iconClass)
        <div class="ui-icon-sample">
            <i class="{{ $iconClass }}" aria-hidden="true"></i>
            <code>
                {{ $iconKey }}
            </code>
        </div>
    @endforeach
</div>

The keys are grouped by the widget that uses them:

Keys	Used by
action.*	shared actions, such as action.delete.
search.*, dropdown.*, tooltip.*	the search input, dropdown carets and field tooltips.
callout.*	the callout types: info, success, warning and danger.
filter.*	the filter widget.
list.*, pagination.*	the list widget: reordering, setup, tree rows, sorting, switch columns and paging.
checkboxlist.*, datepicker.*, sensitive.*	the checkbox list field, the date picker and the sensitive field.
fileupload.*, file.type.*	the file upload widget, with an icon per file type.
recordfinder.*, repeater.*, datatable.*	the record finder, repeater and data table widgets.
codeeditor.*, markdowneditor.*, richeditor.*	the editor toolbars.

Configuration

The icon settings live in config/larajax-icons.php. Publish the file to change them:

php artisan vendor:publish --tag=larajax-ui-config

Option	Description
default	the pack the widgets use. Default: the LARAJAX_ICONS environment value, or phosphor.
fallback	passes names that are not keys through as icon classes, so an icon argument can take classes. Default: true.
packs	the packs by name, each an IconPack class name or an array of keys and classes.
overrides	keys and classes that replace those keys in every pack.

Methods

Method	Description
Ui::extendIcons($extension)	replaces or adds keys in every pack, from an array or a closure.
Ui::registerIconPack($name, $pack)	adds or replaces a pack.

The widgets draw their icons through Ui::icon() and Ui::iconClass(), which resolve a key in the default pack. They exist for the library's own views, so an app rarely needs to call them.