Blade Icons

A package to easily make use of SVG icons in your Laravel Blade views. Originally "Blade SVG" by Adam Wathan.

Icon Packages
Requirements
Installation
Updating
Configuration
Usage
Building Packages
Changelog
Maintainers
License

Icon Packages

This package is a base package to make it easy for you to use SVG icons in your app. If you want to start using a specific icon set, we offer the following ones below:

We're not accepting requests to build new icon packages ourselves but you can start building your own.

Third Party

In addition to the official packages from above there's also quite some third party ones. Thanks to the community for contributing these!

Blade Bootstrap Icons by David H. Sianturi
Blade CSS Icons by khatabWedaa
Blade Eva Icons by Nehal Hasnayeen
Blade Feather Icons by Bruno Falcão
Blade Font Awesome by Owen Voke
Blade Github Octicons by Tim Joosten
Blade Tabler Icons by Ryan Chandler

Requirements

PHP 7.2 or higher
Laravel 7.14 or higher

Installation

Before installing a new package it's always a good idea to clear your config cache:

php artisan config:clear

Then install the package with composer:

composer require blade-ui-kit/blade-icons

After installing the package, publish the configuration and uncomment the default icon set:

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

Updating

Please refer to the upgrade guide when updating the library.

Configuration

Defining Sets

Blade Icons support multiple sets. You can define these by passing a key/value combination in the blade-icons.php config file's sets setting:

<?php

return [
    'sets' => [
        'default' => [
            'path' => 'resources/svg',
        ],
    ],
];

Feel free to add as many sets as you wish. Blade Icons ships with a default set for your app which you may adjust to your liking.

Icon Paths

If you wanted to add icons from a different directory in your app, say resources/images/svg, you can set it like this:

<?php

return [
    'sets' => [
        'default' => [
            'path' => 'resources/images/svg',
        ],
    ],
];

Always make sure you're pointing to existing directories.

Prefixing Icons

In the default icon set the icon prefix will be applied to every icon, but you're free to adjust this in the blade-icons.php config file:

<?php

return [
    'sets' => [
        'default' => [
            'prefix' => 'icon',
        ],
    ],
];

Defining a prefix for every set is required and every prefix should be unique.

When referencing icons with the Blade directive or helper you can omit the prefix to reference icons from the default set. When referencing icons from other sets, using the prefix is required.

When an icon in the default set has a name which collides with a prefix from a set then the icon from the set is retrieved first.

Please note that it's best practice that your icons themselves do not have the prefix in their name. So if you have a prefix in your set called icon and your icons are named icon-example.svg you should rename them to example.svg. Otherwise you can run into unexpected name resolving issues.

Default Classes

You can optionally define classes which will be applied to every icon by filling in the class setting in your blade-icons.php config file:

<?php

return [
    'class' => 'icon icon-default',
];

If you don't want any classes to be applied by default then leave this as an empty string. Additionally, the same option is available in sets so you can set default classes on every set.

The sequence in which classes get applied is <global classes> <set classes> <explicit classes>. You can always override this by passing an explicit class with your attributes. Component classes cannot be overriden.

Usage

There are several ways of inserting icons into your Blade templates. We personally recommend using Blade components, but you can also make use of a Blade directive if you wish.

Components

The easiest way to get started with using icons from sets are Blade components:

<x-icon-camera/>

Icons in subdirectories can be referenced using dot notation:

<x-icon-solid.camera/>

You can also pass classes to your icon components (default classes will be applied as well):

<x-icon-camera class="icon-lg"/>

Or any other attributes for that matter:

<x-icon-camera class="icon-lg" id="settings-icon" style="color: #555" data-baz/>

Note that with Blade components, using a prefix is always required, even when referencing icons from the default set.

Directive

If components aren't really your thing you can make use of the Blade directive instead. If you defined a default icon class in your config and want to render a camera icon with an icon-lg class you can do that like so:

@svg('camera', 'icon-lg')

Any additionally attributes can be passed as a third array argument, and they'll be rendered on the svg element:

@svg('camera', 'icon-lg', ['id' => 'settings-icon'])

If you don't have a class to be defined you can also pass these attributes as the second parameter:

@svg('camera', ['id' => 'settings-icon'])

If you want to override the default classes, pass in the class as an attribute:

@svg('camera', ['class' => 'icon-lg'])

Attributes without a key, are supported too:

@svg('camera', ['data-foo'])

Helper

If you'd like, you can use the svg helper to expose a fluent syntax for setting SVG attributes:

{{ svg('camera')->id('settings-icon')->dataFoo('bar')->dataBaz() }}

Building Packages

If you're interested in building your own third party package to integrate an icon set, it's pretty easy to do so. If want to learn how to create packages first I can recommend these two excellent courses:

Make sure to load your SVGs from the boot method of your package's service provider. Provide the path to your SVGs and provide your own unique set name and component prefix:

use BladeUI\Icons\Factory;

public function register(): void
{
    $this->callAfterResolving(Factory::class, function (Factory $factory) {
        $factory->add('heroicons', [
            'path' => __DIR__ . '/../resources/svg',
            'prefix' => 'heroicon',
        ]);
    });
}

Now your icons can be referenced using a component, directive or helper:

<x-heroicon-o-bell />

@svg('heroicon-o-bell')

{{ svg('heroicon-o-bell') }}

Don't forget to make blade-ui-kit/blade-icons a requirement of your package's composer.json.

Changelog

Check out the CHANGELOG in this repository for all the recent changes.

Maintainers

Blade Icons is developed and maintained by Dries Vints.

License

Blade Icons is open-sourced software licensed under the MIT license.

davidhsianturi / blade-icons