DOCSEARCHbyAlgolia
Submit Docs

Blade Icons Documentation

repository·1.x·Indexed 25 days ago

https://github.com/driesvints/blade-icons

A Laravel package that allows the use of SVG icon sets as Blade components, via the @svg directive, or through the svg() helper. It supports custom icon sets, caching for performance, fallback icons, and accessibility features. The package also includes a CLI tool, blade-icons-generate, to automate the creation of icon components from SVG files for third-party packages.

Tokens
3.8K
Snippets
16
Records
22
Agent score
81%

What's inside Blade Icons

  1. Explore Blade Icons icon packages

    1.x

    Blade Icons is a base package for using SVG icons in Laravel applications. While the core package provides the functionality, most icon sets are available as separate third-party packages. You can install specific icon sets (e.g., blade-heroicons, blade-font-awesome, blade-lucide-icons) to add different icon libraries to your project.

    Note: The maintainers do not build new icon packages themselves, but the community provides a wide variety of sets including Material Design, Font Awesome, Heroicons, and many others.

  2. XML tag stripping in Blade Icons 1.0.0

    1.x
    Starting with version 1.0.0, Blade Icons automatically strips XML tags from SVG icons. This is intended to simplify the rendering of SVG content. If your application logic specifically relies on these XML tags being present in the output, you should be aware of this change before upgrading.

  3. Insert icons using Blade components

    1.x

    The recommended way to use icons is via Blade components. Icons from sets are available as <x-prefix-iconname/>.

    • Subdirectories: Use dot notation for icons in subdirectories (e.g., <x-icon-solid.camera/>).
    • Attributes: You can pass standard HTML attributes like class, id, style, and data-* directly to the component.
    • Prefixes: When using components, a prefix is always required, even for the default set.

    Note: To use the default component syntax <x-icon name="camera"/>, you must ensure the default component is enabled in your configuration.

    <x-icon-camera/>

<x-icon-solid.camera/>

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

  4. Use SVG icons in Blade views

    1.x

    Blade Icons allows you to use SVG icons in your Laravel Blade templates using either Blade components or a directive.

    1. Blade Components: Use the <x-icon-{name} /> syntax. The component name is prefixed with icon- followed by the icon name.
    2. @svg Directive: Use the @svg('name', 'attributes') directive to render an icon with specific CSS classes or attributes.

  5. Manage icon caching

    1.x

    To improve performance, especially with large icon sets or Blade components, you can cache the icon manifest. This creates a blade-icons.php file in bootstrap/cache.

    Important: When icons are cached, you cannot add new icons, change paths, or install/remove icon packages without clearing the cache first.

    • Enable caching (recommended for production): php artisan icons:cache
    • Clear cache (run before making changes): php artisan icons:clear
    • Clear views (run after adding/renaming icons): php artisan view:clear
    php artisan icons:cache
php artisan icons:clear
php artisan view:clear

  6. Defer icons to reduce DOM size

    1.x

    If you are rendering many instances of the same icon on a single page, you can use the defer attribute on the <x-icon> component. This pushes the SVG content to a Blade stack named bladeicons instead of inlining it multiple times.

    1. Add defer to your component: <x-icon-camera defer />.
    2. Load the stack at the bottom of your page (e.g., before the closing </body> tag) inside a hidden SVG element.

    Warning: Deferring only works with the <x-icon> component. It is not supported by the @svg directive or the svg() helper.

    JavaScript Usage: You can provide a custom identifier via defer="my-custom-hash". In JavaScript, use the <use> element to reference it: <svg><use href="#icon-my-custom-hash"></use></svg>.

    <x-icon-camera defer />

<!-- At the bottom of your page -->
<svg hidden class="hidden">
    @stack('bladeicons')
</svg>
    function icon() {
    return <svg><use href="#icon-my-custom-hash"></use></svg>
}

  7. Generate icons for your package

    1.x

    You can automate icon generation by creating a config/generation.php file in your icon package. This file defines how icons are moved from a source (like node_modules) to your package's resources/svg directory.

    Configuration Options:

    • source: The directory containing source icons.
    • destination: The directory where icons will be saved.
    • input-prefix / output-prefix: Strips or adds prefixes to icon names.
    • input-suffix / output-suffix: Strips or adds suffixes to icon names.
    • safe: If true, prevents deletion of existing icons.
    • after: A callback function to manipulate the icon file during generation.

    Command: Run the generator from the root of your icon package using: vendor/bin/blade-icons-generate

    // config/generation.php
return [
    [
        'source' => __DIR__.'/../node_modules/heroicons/outline',
        'destination' => __DIR__.'/../resources/svg',
        'input-prefix' => 'o-',
        'output-prefix' => 'o-',
        'input-suffix' => '-o',
        'output-suffix' => '-o',
        'safe' => true,
        'after' => static function (string $icon, array $config, SplFileInfo $file) {
            // ...
        },
    ],
];
    vendor/bin/blade-icons-generate

  8. General upgrade steps for Blade Icons

    1.x

    When updating Blade Icons to a new version, perform the following steps to ensure the cache is cleared and changes are reflected in your application:

    1. Clear the icon cache: php artisan icons:clear
    2. Clear the view cache: php artisan view:clear

    If you have a published configuration file, you must manually sync it with the configuration file from the version you are upgrading to.

    php artisan icons:clear
php artisan view:clear

  9. Install Blade Icons

    1.x

    Install the package using Composer and publish the configuration file. After publishing, ensure you uncomment the default icon set in the config file and verify that the defined path (defaulting to resources/svg) exists in your project.

    composer require blade-ui-kit/blade-icons
php artisan vendor:publish --tag=blade-icons

  11. Add accessibility to icons

    1.x

    To make icons accessible, you can add a title attribute. This automatically applies semantic features to the SVG:

    • A <title> child element with a unique ID.
    • A title attribute on the <svg> element.
    • role="img".
    • aria-labelledby pointing to the title ID.

    If an icon is purely decorative and has no semantic meaning, add aria-hidden="true" to reduce document clutter.

    <x-icon-camera title="camera" />

@svg('camera', ['title' => 'camera'])

  12. Configure fallback icons

    1.x

    You can define fallback icons to prevent errors when a requested icon is missing.

    1. Set-specific fallback: Define a fallback key within a specific set. This icon will be used if an icon from that set is not found.
    2. Global fallback: Define a top-level fallback key in the config. This is used if a set doesn't have its own fallback defined. It can reference any icon from any registered set (e.g., prefix-icon-name).

    Warning: Fallback icons do not work when using Blade Components; Laravel will throw an exception if the component cannot be found. Use them with other Blade Icons usages instead.

    // Set-specific fallback
'sets' => [
    'default' => [
        'fallback' => 'cake',
    ],
],

// Global fallback
'fallback' => 'heroicon-cake',
    'sets' => [
    'default' => [
        'fallback' => 'cake',
    ],
],