teksite / icon-laravel

1.0.0 2026-08-29 12:11 UTC

Requires

• php: ^8.3
• laravel/framework: ^13.0

Requires (Dev)

• orchestra/testbench: ^11.0
• phpunit/phpunit: ^11.5|^12.5

MIT

• Sina Zangiband

Published on Packagist.org on 2026-08-29 12:14 UTC

README

A simple, lightweight Laravel package for using SVG icons directly in Blade components.

Requirements

• PHP 8.3+
• Laravel 13+

Installation

Install the package with Composer:

composer require teksite/icon-laravel

The service provider is automatically discovered by Laravel.

Publishing Assets

Publish the package configuration:

php artisan vendor:publish --tag=icon-setting

Publish the icon assets:

php artisan vendor:publish --tag=icon-assets

You can also publish each asset group separately:

php artisan vendor:publish --tag=icons-outline
php artisan vendor:publish --tag=icons-solid
php artisan vendor:publish --tag=icons-picker

The published files are placed under:

{public_path}/vendor/icons/

The configuration file is:

config/icon-setting.php

Configuration

The default configuration looks like this:

<?php

return [

    'cache' => [
        'key' => 'svg_icons.icons',
        'enabled' => env('SVG_ICONS_CACHE_ENABLED', false),
        'ttl' => env('SVG_ICONS_CACHE_TTL', 2592000),
    ],

    'path' => [
        'solid' => public_path('vendor/icons/solid.json'),
        'outline' => public_path('vendor/icons/outline.json'),
    ],

    'component' => 'components.icon',

];

Icon Sources

The package supports multiple icon types.

By default:

'path' => [
    'outline' => public_path('vendor/icons/outline.json'),
],

Custom icon JSON files take priority when they exist.

If a configured file does not exist, the package automatically falls back to the package's bundled resource:

src/resources/{type}.json

For example:

src/resources/outline.json
src/resources/solid.json

You can define additional custom icon types by adding them to the configuration:

'path' => [
    'outline' => public_path('vendor/icons/outline.json'),
    'solid' => public_path('vendor/icons/solid.json'),
    'custom' => public_path('vendor/icons/custom.json'),
],

The icon type must contain only letters, numbers, underscores, or hyphens.

Using Icons

The package provides two Blade components:

<x-icon />

and:

<x-tkicon />

Both components use the same icon manager and support the same main properties.

Basic Usage

<x-icon icon="home" />

or:

<x-tkicon icon="home" />

The default icon type is:

outline

To use a solid icon:

<x-icon icon="home" type="solid" />

Component Attributes

The component supports the following properties:

icon
title
type
viewbox
x
y
width
height
strokeWidth
strokeLinecap
strokeLinejoin

Example:

<x-icon
    icon="home"
    type="outline"
    title="Home"
    width="32"
    height="32"
    strokeWidth="1.5"
/>

Additional HTML attributes can also be passed to the component:

<x-icon
    icon="home"
    class="text-blue-500"
    id="home-icon"
/>

The component merges the provided class with its default classes.

Generated SVG

The component renders an SVG element similar to:

<svg
    x="0"
    y="0"
    width="24"
    height="24"
    viewBox="0 0 24 24"
    class="tkicon home outline-icon"
    data-icon="home"
    stroke-width="1"
    stroke-linecap="round"
    stroke-linejoin="round"
    xmlns="http://www.w3.org/2000/svg"
>
    ...
</svg>

Custom Component View

The default component view is configured as:

'component' => 'components.icon',

You can change it in:

config/icon-setting.php

For example:

'component' => 'icons.svg',

The configured view receives:

[
    'path' => $path,
]

The icon component also exposes its normal Blade component properties and attributes.

If the configured view does not exist, the Icon component logs an error and falls back to an inline SVG renderer.

Difference Between icon and tkicon

Both components provide the same basic functionality.

<x-icon>

<x-icon> supports a configurable Blade view through:

'component' => 'components.icon',

If the configured view exists, it is used for rendering.

If it does not exist, the component uses its built-in fallback renderer.

<x-tkicon>

<x-tkicon> always uses its built-in inline renderer.

Example:

<x-tkicon icon="home" />

IconManager

The main service responsible for loading and rendering icons is:

Teksite\IconLaravel\Service\IconManager

It is registered as a Laravel singleton.

You can resolve it from the container:

$iconManager = app(\Teksite\IconLaravel\Service\IconManager::class);

Get an Icon

You can retrieve an icon as a complete SVG:

$icon = app(\Teksite\IconLaravel\Service\IconManager::class)
    ->getIcon('home');

By default, the icon type is:

outline

To specify another type:

$icon = app(\Teksite\IconLaravel\Service\IconManager::class)
    ->getIcon('home', type: 'solid');

Get the Raw SVG Path

The render argument can be disabled to retrieve only the SVG path/content:

$path = app(\Teksite\IconLaravel\Service\IconManager::class)
    ->getIcon(
        'home',
        type: 'outline',
        render: false
    );

This is useful when the SVG element itself needs to be controlled by a Blade component or custom renderer.

SVG Attributes

When rendering an icon directly through IconManager, attributes can be passed as an array:

$icon = app(\Teksite\IconLaravel\Service\IconManager::class)
    ->getIcon(
        'home',
        attributes: [
            'class' => 'w-6 h-6',
            'width' => 24,
            'height' => 24,
            'aria-hidden' => true,
        ]
    );

The package escapes attribute names and values before rendering them.

Check Whether an Icon Exists

$exists = app(\Teksite\IconLaravel\Service\IconManager::class)
    ->hasIcon('home');

For a specific type:

$exists = app(\Teksite\IconLaravel\Service\IconManager::class)
    ->hasIcon('home', 'solid');

The result is a boolean.

Get Icon Names

Get all icon names for a specific type:

$names = app(\Teksite\IconLaravel\Service\IconManager::class)
    ->getIconNames('outline');

Get icon names grouped by type:

$names = app(\Teksite\IconLaravel\Service\IconManager::class)
    ->getIconNames();

Get All Icons

Get all icons as raw path definitions:

$icons = app(\Teksite\IconLaravel\Service\IconManager::class)
    ->getAll(render: false);

Get all icons as rendered SVG elements:

$icons = app(\Teksite\IconLaravel\Service\IconManager::class)
    ->getAll();

Icon JSON Format

Icons are stored as JSON objects where the key is the icon name and the value is the SVG path/content.

Example:

{
    "home": "<path d=\"...\" />",
    "user": "<path d=\"...\" />"
}

Icon names must match:

[a-zA-Z0-9_-]+

Invalid icon names are ignored while loading the JSON file.

Empty or invalid path values are also ignored.

Cache

Icon loading can be cached.

Caching is disabled by default:

'cache' => [
    'enabled' => false,
],

Enable it through the environment:

SVG_ICONS_CACHE_ENABLED=true

The default cache TTL is 24 hours:

SVG_ICONS_CACHE_TTL=2592000

You can customize the cache key:

SVG_ICONS_CACHE_ENABLED=true
SVG_ICONS_CACHE_TTL=2592000

Or configure it directly in:

config/icon-setting.php

Example:

'cache' => [
    'key' => 'svg_icons.icons',
    'enabled' => true,
    'ttl' => 2592000,
],

Clearing the Icon Cache

The package provides:

Teksite\IconLaravel\Support\CacheManager

To clear the icon cache:

\Teksite\IconLaravel\Support\CacheManager::clearCache();

For example:

use Teksite\IconLaravel\Support\CacheManager;

CacheManager::clearCache();

This is useful after changing or replacing icon JSON files while caching is enabled.

Debugging Missing Icons

If an icon does not exist and Laravel is running with:

APP_DEBUG=true

the package renders a small warning indicator:

⚠️

with the missing icon name.

When debug mode is disabled, missing icons return an empty string instead.

Creating Custom Icons

You can add your own icon collection.

For example, create:

public/vendor/icons/custom.json

with:

{
    "my-icon": "<path d=\"...\" />"
}

Then configure it:

'path' => [
    'outline' => public_path('vendor/icons/outline.json'),
    'solid' => public_path('vendor/icons/solid.json'),
    'custom' => public_path('vendor/icons/custom.json'),
],

You can then use:

<x-icon icon="my-icon" type="custom" />

Blade Registration

The package registers the following Blade components:

<x-icon />
<x-tkicon />

Their aliases are registered by the service provider:

Blade::component('icon', Icon::class);
Blade::component('tkicon', TekIcon::class);

Security

Icon names and icon types are validated before lookup.

Only identifiers matching:

[a-zA-Z0-9_-]+

are accepted.

HTML attributes generated by IconManager are escaped using:

htmlspecialchars(
    $value,
    ENT_QUOTES | ENT_SUBSTITUTE,
    'UTF-8'
);

Icon path content is treated as SVG content and is inserted directly into the generated SVG. Therefore, custom icon JSON files should only contain trusted SVG definitions.

License

This package is open-sourced software licensed under the MIT license.

Author

Sina Zangiband

Email:

[e-mail]

Contact

• teksite.net
• laratek.ir
• teksite.net

GitHub

Repository:

https://github.com/teksite/icon-laravel