README

This is a laravel package to customize the icons for Livewire Flux. It builds the icons from various vendors into a flux:icon component.

Installation

Generally you want to install this package only in your local development environment and build and publish the icons you need.

composer require --dev ympact/flux-icons

Icon Vendor Support

Building icons

You will need to build the icons yourself once the package is installed. This can be done using the artisan command flux-icons:build. You can optionally pass the vendor name as the first argument.

php artisan flux-icons:build tabler --icons=confetti,confetti-off

The artisan script will try to install the vendor's icon package for you using npm install. In case you did not provide any arguments, the script will walk you through all options

Options

Usage

Since this package publishes all icons to resources/views/flux/icon/{vendor}/ you can simply use the Blade convention of referencing the icons within your flux:icon component. So for example:

<flux:icon.tabler.confetti />
or
<flux:icon name="tabler.confetti-off"/>

Publish config

You can publish the config file to adjust settings for a specific vendor or add your own vendor. For example adjusting the stroke width of outline icons. In case you add your own vendor, please share or make a PR so others can use it too!

php artisan vendor:publish --tag=flux-icons-config

Publish specific vendor callbacks

For some vendors callbacks str defined (see the config). Adjusting these callbacks can be done by publishing the class using the following command:

php artisan flux-icons:publish {vendor}

When adjusting the callback for a vendor, make sure you also publish the config file and reference the correct class.

Advanced configuration

General config

Vendor specific configuration

The vendor specific configuration sits within the vendors key. Each vendor should have a key. That key will be used as directory name when exporting the icons.

'vendors' => [
    'tabler' => [
        'vendor' => 'Tabler',
        'namespace' => 'tabler',
        'package' => '@tabler/icons',
        'variants' => [ 
            //...
        ]
    ]
 ]

Variants

    'variants' => [
        'outline' => [
            'source' => [], // see config options below
            'template' => 'outline',
            'fallback' => 'default', 
            'stroke_width' => false, 
            'size' => 24,
            'attributes' = []
        ],
        'solid' => [
            'source' => [],
        ],
        'mini' => [
            'base' => 'solid'
        ],
        'micro' => [
            'base' => 'solid'
        ],
    ]

Source

The source directories specify where the script can find the outline and solid versions of the icons you want to build. In case the vendor uses a prefix or suffix for the icons, we want to configure it here to determine the basename of the icon and make them easier accessible in flux.

[
    'dir' => 'node_modules/vendor/icons/...',
    'prefix' => null,
    'suffix' => null 
    'filter' => [ Ympact\FluxIcons\Services\Vendor\VendorName::class, 'filter']
]

Filter

An optional filter callback can be defined to indicate whether a file in the directory should be used as outline or solid respectively. The function gets three arguments passed: $file, $icons, $variant:

• $file
• icons is an array of icons that the user requested to build. This is passed by reference in case this array needs to be adjusted. See the Mdi class as example.
• $variant

Optionally callbacks can be defined on dir, prefix and suffix to adjust these according to the icon variant. The $variant passed to the callback defines which variant is currently build (outline, solid, mini, micro).

'solid' => [ 
    [
        'dir' => 'node_modules/vendor/icons/icons/filled', 
        'prefix' => null, 
        'suffix' => [ Ympact\FluxIcons\Services\Vendor\VendorName::class, 'sourceSolidSuffix']
    ],
],

Fallbacks for icon variants

Due to the way the flux icon component is made, it requires 4 variants: an outline and preferably a solid of three sizes:

• solid - 24px
• mini - 20px
• micro - 16px

Using the configuration of the vendor, you can determine how to handle the building of the icon when there is no source file for a certain variant. The options are:

Callbacks

The configuration file provides various options on which callback can be defined. To keep the config file serializable, the callbacks should be defined in a separate class and referenced as above. See vendor.php.stub for reference of the available callbacks.

Additional icons

This package also provide some custom icons that can be published:

They can be published using

php artisan vendor:publish --tag=flux-icons-icons

• An empty icon, can be useful for simple logic in your blade or components:

  <flux:icon name="{{ $icon ?? 'flux-icons.empty' }}" />

• A placeholder avatar icon, using an icon or initials

  <flux:icon.flux-icons.avatar-placeholder name="Maurits Korse" color="green" />
  <flux:icon.flux-icons.avatar-placeholder icon color="green" />

  This icon has additional properties:

  • icon (void|string): uses the Heroicon user icon as image.
  • name (string): instead of an icon two initials of a name will be shown. You can pass the full name (Maurits Korse) or just the initials (MK)
  • color (string): colorizing the icon using the same as Flux badges

Roadmap

• Add/Improve command for updating/rebuilding icons
• Adding more vendors
• Helper script to create configurations for new vendors
• Improving testing
• Documentation
• Support other variants (duotone, etc.)