Blade Lucide Icons

https://github.com/mallardduck/blade-lucide-icons
Admin
A Laravel package that integrates Lucide Icons as Blade components for easy use of SVG icons in...
Tokens:20,342
Snippets:163
Trust Score:8.7
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Initial setup with make setup

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/CONTRIBUTING.md

Run this command for first-time setup. It installs git hooks and initializes/syncs the lucide submodule.

```bash
make setup
```

--------------------------------

### Example config/blade-lucide-icons.php

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/api-reference/blade-lucide-icons-service-provider.md

Example configuration file for the blade-lucide-icons package. Unset options fall back to package defaults.

```php
// config/blade-lucide-icons.php
return [

    'prefix' => 'lucide',

    'fallback' => 'circle-alert',   // shown when an icon name cannot be found

    'class' => 'w-6 h-6',

    'attributes' => [
        'width' => 50,
        'height' => 50,
    ],
];
```

--------------------------------

### Install blade-lucide-icons via Composer

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/README.md

Install the package via Composer. Requires PHP 8.1 or higher and Laravel 8.0 or higher.

```bash
composer require mallardduck/blade-lucide-icons
```

--------------------------------

### Override icon set configuration in config/blade-lucide-icons.php

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/configuration.md

Example override in the consuming application's config/blade-lucide-icons.php. Shows how to set the prefix, fallback icon, default classes, and default attributes for the icon set.

```php
return [
    'prefix' => 'lucide',
    'fallback' => 'circle-alert',
    'class' => 'w-6 h-6 text-gray-500',
    'attributes' => [
        'width' => 24,
        'height' => 24,
    ],
];
```

--------------------------------

### Catch framework exceptions in Laravel consumer

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/errors.md

PHP example for library consumers (Laravel applications). There are no package-specific error types; framework exceptions propagate normally. Catch the upstream types from blade-ui-kit/blade-icons and the container/config layer. This snippet shows catching any Throwable during container factory resolution and logging it to keep the app bootable.

```php
try {
    // any boot-path failure would surface here during app bootstrap;
    // the container factory resolution below is the only package operation
    // that touches external infrastructure in register()
    $container->make(\BladeUI\Icons\Factory::class);
} catch (Throwable $e) {
    // framework-level failure: log and keep the app bootable
    log($e);
}
```

--------------------------------

### Available make commands

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/CONTRIBUTING.md

Lists all available make commands: help, sync, update, install-hooks, and test.

```bash
make help          # Show all available commands
make sync          # Manually sync submodules
make update        # Pull latest changes and sync submodules
make install-hooks # Install git hooks
make test          # Run test suite
```

--------------------------------

### boot(): Register publish tags for assets and config

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/api-reference/blade-lucide-icons-service-provider.md

Public boot method that runs only in console context. Registers publish tags 'blade-lucide-icons' for the SVG assets and 'blade-lucide-icons-config' for the config files. In non-console contexts it is a no-op.

```php
public function boot(): void
{
    if ($this->app->runningInConsole()) {
        $this->publishes([
            __DIR__.'/../resources/svg' => public_path('vendor/blade-lucide-icons'),
        ], 'blade-lucide-icons');

        $this->publishes([
            __DIR__.'/../config/blade-lucide-icons.php' => $this->app->configPath('blade-lucide-icons.php'),
            __DIR__.'/../config/blade-lucide-lab-icons.php' => $this->app->configPath('blade-lucide-lab-icons.php'),
        ], 'blade-lucide-icons-config');
    }
}
```

--------------------------------

### Running tests with make test or phpunit

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/CONTRIBUTING.md

Two ways to run the test suite: using make test or directly invoking PHPUnit.

```bash
make test
# or
php vendor/bin/phpunit
```

--------------------------------

### bucketFor function signature

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/api-reference/cli-detect-icon-changes.md

Maps a repo-relative path to its icon set bucket: 'icons' for resources/svg/icons/, 'lab' for resources/svg/lab/, and null otherwise.

```php
function bucketFor(string $path): ?string
```

--------------------------------

### Run detect-icon-changes.php

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/bin/README.md

Analyzes icon file changes between commits and outputs a JSON object with bump type and change details for core and lab icons.

```bash
php bin/detect-icon-changes.php
```

--------------------------------

### register() method for BladeLucideIconsServiceProvider

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/api-reference/blade-lucide-icons-service-provider.md

Registers the package config and schedules a callback to add the 'lucide' and 'lucide-lab' icon sets to the BladeUI Factory after it is resolved. The path option is always set first; user config keys override it if present.

```php
public function register(): void
{
    $this->registerConfig();

    $this->callAfterResolving(Factory::class, function (Factory $factory, Container $container) {
        $config = $container->make('config')->get('blade-lucide-icons', []);
        $factory->add('lucide', array_merge(['path' => __DIR__.'/../resources/svg/icons'], $config));

        $labConfig = $container->make('config')->get('blade-lucide-lab-icons', []);
        $factory->add('lucide-lab', array_merge(['path' => __DIR__.'/../resources/svg/lab'], $labConfig));
    });
}
```

--------------------------------

### Basic patch bump with output

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/api-reference/cli-bump-version.md

Runs a basic patch bump with the core train updated only. The command outputs the new version number, shown here as 2.0.25.

```bash
php bin/bump-version.php patch 1.52.0 -
```

```text
2.0.25
```

--------------------------------

### Manual submodule management commands

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/CONTRIBUTING.md

Commands to manually initialize and update submodules if you prefer not to use git hooks.

```bash
# Initialize and update all submodules
git submodule update --init --recursive

# Update submodules to latest commit referenced by main repo
git submodule update --recursive
```

--------------------------------

### Run bump-version.php

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/bin/README.md

Bumps the package version and updates CHANGELOG.md. Requires bump type, Lucide core version, Lucide lab version, and optional changes JSON.

```bash
php bin/bump-version.php <bump_type> <lucide_version> <lucide_lab_version> [changes_json]
```

--------------------------------

### IconSetConfig array from config/blade-lucide-icons.php

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/types.md

Defines the IconSetConfig shape returned from config/blade-lucide-icons.php and config/blade-lucide-lab-icons.php. The 'prefix' key is required and must be unique; 'fallback', 'class', and 'attributes' are optional with defaults of '', '', and [] respectively. The 'attributes' array accepts string-to-scalar pairs applied by default to all icons in the set.

```php
return [

    'prefix' => 'lucide',        // respectively 'lucidelab'

    'fallback' => '',

    'class' => '',

    'attributes' => [
        // 'width' => 50,
        // 'height' => 50,
    ],

];
```

--------------------------------

### registerConfig(): Merge package config files

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/api-reference/blade-lucide-icons-service-provider.md

Private method that merges the package's two config files into the application configuration under the keys 'blade-lucide-icons' and 'blade-lucide-lab-icons' using the mergeConfigFrom helper. It is called from register() before the factory registration callback, ensuring config reads observe merged defaults.

```php
private function registerConfig(): void
{
    $this->mergeConfigFrom(__DIR__.'/../config/blade-lucide-icons.php', 'blade-lucide-icons');
    $this->mergeConfigFrom(__DIR__.'/../config/blade-lucide-lab-icons.php', 'blade-lucide-lab-icons');
}
```

--------------------------------

### Publish SVG assets and reference in Blade view

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/api-reference/blade-lucide-icons-service-provider.md

Publishes the raw SVG assets to public/vendor/blade-lucide-icons and then references one in a Blade view using the asset() helper. The --force flag is used to overwrite existing files.

```bash
php artisan vendor:publish --tag=blade-lucide-icons --force
```

```blade
<img src="{{ asset('vendor/blade-lucide-icons/cloud-moon.svg') }}" width="10" height="10"/>
```

--------------------------------

### Return generator-set definitions for core and lab icons

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/api-reference/icon-generation.md

Returns the generator-set definitions for the blade-lucide-icons package. It defines two sets: one for core icons (from ../lucide/icons to ../resources/svg/icons) and one for lab icons (from ../lucide/lab to ../resources/svg/lab). Each set uses the $svgNormalization callback after generation and sets 'safe' => true to indicate generated files may be safely overwritten.

```php
return [
    [
        'source' => __DIR__.'/../lucide/icons',
        'destination' => __DIR__.'/../resources/svg/icons',
        'after' => $svgNormalization,
        'safe' => true,
    ],
    [
        'source' => __DIR__.'/../lucide/lab',
        'destination' => __DIR__.'/../resources/svg/lab',
        'after' => $svgNormalization,
        'safe' => true,
    ],
];
```

--------------------------------

### Publish blade-lucide-icons config

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/README.md

Publish the blade-lucide-icons.php config file to customize default classes, attributes, and other Blade Icons features.

```bash
php artisan vendor:publish --tag=blade-lucide-icons-config
```

--------------------------------

### Patch bump with change data and resulting CHANGELOG entry

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/api-reference/cli-bump-version.md

Runs a patch bump with change data (as produced by cli-detect-icon-changes.md) to render per-iconset bullets. The resulting CHANGELOG entry shape is shown.

```bash
php bin/bump-version.php patch 1.52.0 - '{"bump_type":"patch","icons":{"bump_type":"patch","changes":{"added":["layout-grid-circles","printer-3d"],"removed":[],"modified":[]},"summary":{"added_count":2}},"lab":{"bump_type":"none","changes":{"added":[],"removed":[],"modified":[]},"summary":{"added_count":0}}}'
```

```markdown
## 2.0.25 - (2026-10-05)
### Added
- Added 2 new icon(s): `layout-grid-circles`, `printer-3d`

### Updates
- Update Lucide icons to `v1.52.0`
```

--------------------------------

### Publish raw SVG icons

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/README.md

Publish the raw SVG icon assets to the public/vendor directory. The --force flag overwrites existing files.

```bash
php artisan vendor:publish --tag=blade-lucide-icons --force
```

--------------------------------

### Use solid Lucide icon component

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/README.md

Reference solid icons using the same component syntax.

```blade
<x-lucide-bike />
```

--------------------------------

### summarize function signature

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/api-reference/cli-detect-icon-changes.md

Builds the per-set report object with bump_type, changes (added/removed/modified), and summary counts. Icon names are SVG basenames without the .svg suffix.

```php
function summarize(array $added, array $removed, array $modified): array
```

--------------------------------

### BLADE <x-lucidelab-{icon-name} />

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/api-reference/blade-icon-components.md

Dynamic Blade component for rendering icons from the 'lucide-lab' set.

```APIDOC
## [BLADE] <x-lucidelab-{icon-name} />

### Description
Renders an inline SVG icon from the `lucide-lab` icon set as a self-closing Blade component. The component name is formed from the set prefix (`lucidelab`) and the icon filename (minus `.svg`).

### Component Syntax
```blade
<x-lucidelab-{icon-name} [class="..."] [style="..."] [arbitrary attribute] />
```

### Parameters
- **{icon-name}** (string) - Required - The icon name, e.g. `avocado`, `bacon`, `whale-narwhal`. Hyphens are allowed and form part of the component name.
- **class** (string) - Optional - Appended to the root `<svg>` element's `class` attribute.
- **style** (string) - Optional - Appended to the root `<svg>` element's `style` attribute.
- **arbitrary attribute** - Optional - Passed through to the root `<svg>` element.

### Example
```blade
<x-lucidelab-avocado class="w-4 h-4" />
```

### Response
Renders an inline SVG element with the specified attributes.
```

--------------------------------

### runGitCommand function signature

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/api-reference/cli-detect-icon-changes.md

Declares the file-local helper that executes a shell command using proc_open/proc_close with three pipes. Returns an array with output lines and exit code.

```php
function runGitCommand(string $command): array
```

--------------------------------

### Imports for BladeLucideIconsServiceProvider

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/api-reference/blade-lucide-icons-service-provider.md

Imports the Factory and Container classes used in the register method.

```php
use BladeUI\Icons\Factory;
use Illuminate\Contracts\Container\Container;
```

--------------------------------

### BLADE <x-lucide-{icon-name} />

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/api-reference/blade-icon-components.md

Dynamic Blade component for rendering icons from the 'lucide' set.

```APIDOC
## [BLADE] <x-lucide-{icon-name} />

### Description
Renders an inline SVG icon from the `lucide` icon set as a self-closing Blade component. The component name is formed from the set prefix (`lucide`) and the icon filename (minus `.svg`).

### Component Syntax
```blade
<x-lucide-{icon-name} [class="..."] [style="..."] [arbitrary attribute] />
```

### Parameters
- **{icon-name}** (string) - Required - The icon name, e.g. `activity`, `alarm-clock-plus`, `bike`. Hyphens are allowed and form part of the component name.
- **class** (string) - Optional - Appended to the root `<svg>` element's `class` attribute.
- **style** (string) - Optional - Appended to the root `<svg>` element's `style` attribute.
- **arbitrary attribute** - Optional - Passed through to the root `<svg>` element.

### Example
```blade
<x-lucide-alarm-clock-plus class="w-4 h-4" />
```

### Response
Renders an inline SVG element with the specified attributes.
```

--------------------------------

### Feed report into release pipeline with jq

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/api-reference/cli-detect-icon-changes.md

Feeds the JSON report into the release pipeline: captures the script output, extracts the bump_type with jq, and passes it along with the version and report to bump-version.php.

```bash
CHANGES_JSON=$(php bin/detect-icon-changes.php)
BUMP_TYPE=$(echo "${CHANGES_JSON}" | jq -r '.bump_type')
php bin/bump-version.php "${BUMP_TYPE}" "1.52.0" "-" "${CHANGES_JSON}"
```

--------------------------------

### Invoke dynamic Blade icon components with x-lucide and x-lucidelab

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/api-reference/blade-icon-components.md

Invocation contract for dynamic Blade icon components. The first block uses the default prefix 'lucide' for icons in the 'lucide' set; the second uses the default prefix 'lucidelab' for icons in the 'lucide-lab' set. Both accept class, style, and arbitrary attributes that are passed to the root SVG element.

```blade
<x-lucide-{icon-name} [class="..."] [style="..."] [arbitrary attribute] />
```

```blade
<x-lucidelab-{icon-name} [class="..."] [style="..."] [arbitrary attribute] />
```

--------------------------------

### Factory registration options: array_merge for icon sets

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/types.md

These two array_merge calls are used in src/BladeLucideIconsServiceProvider.php to set the 'path' key for each icon set before merging user configuration. The first sets the path to the icons directory, the second to the lab directory. Any duplicate keys from the user config override the package-provided path.

```php
array_merge(['path' => __DIR__.'/../resources/svg/icons'], $config)
```

```php
array_merge(['path' => __DIR__.'/../resources/svg/lab'], $labConfig)
```

--------------------------------

### Compilation with style argument

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/api-reference/blade-icon-components.md

Demonstrates how the style argument is merged into the root <svg> element's style attribute. The snapshot test CompilesIconsTest__it_can_add_styles_to_icons__1.xml verifies this behavior.

```blade
<x-lucide-anchor style="color: #555"/>
```

```xml
<?xml version="1.0"?>
<svg xmlns="http://www.w3.org/2000/svg" style="color: #555" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
  ...
</svg>
```

--------------------------------

### Class declaration for BladeLucideIconsServiceProvider

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/api-reference/blade-lucide-icons-service-provider.md

Declares the package's only PHP class as final, preventing subclassing, and extends Illuminate\Support\ServiceProvider.

```php
final class BladeLucideIconsServiceProvider extends ServiceProvider
```

--------------------------------

### Compilation with class argument

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/api-reference/blade-icon-components.md

Demonstrates how the class argument is merged into the root <svg> element's class attribute. The snapshot test CompilesIconsTest__it_can_add_classes_to_icons__1.xml verifies this behavior.

```blade
<x-lucide-bell class="w-6 h-6 text-gray-500"/>
```

```xml
<?xml version="1.0"?>
<svg xmlns="http://www.w3.org/2000/svg" class="w-6 h-6 text-gray-500" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
  ...
</svg>
```

--------------------------------

### Use raw SVG icon in view

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/README.md

Use the published raw SVG icons as assets in your views, referencing the file path under vendor/blade-lucide-icons.

```blade
<img src="{{ asset('vendor/blade-lucide-icons/cloud-moon.svg') }}" width="10" height="10"/>
```

--------------------------------

### Handle CLI exit codes in shell

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/errors.md

Shell handling for CLI consumers. The first command checks the exit code of the bump script and prints an error to stderr if it fails. The second command shows an expected failure case (a 'none' bump) that exits with code 0 and only writes informational output to stderr.

```bash
php bin/bump-version.php patch 1.52.0 - >/dev/null || {
    echo "bump failed" >&2
    exit 1
}
```

```bash
php bin/bump-version.php none - -
```

--------------------------------

### Laravel auto-discovery declaration in composer.json

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/api-reference/blade-lucide-icons-service-provider.md

Composer configuration for Laravel auto-discovery of the service provider. This is required only if the package is not auto-discovered; the package is auto-discovered via extra.laravel.providers.

```json
{
    "extra": {
        "laravel": {
            "providers": [
                "MallardDuck\\LucideIcons\\BladeLucideIconsServiceProvider"
            ]
        }
    }
}
```

--------------------------------

### Early exit for a none bump in a shell conditional

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/api-reference/cli-bump-version.md

Shows an early exit for a `none` bump, wrapping cleanly in shell conditionals. The command outputs the new version and the script echoes it.

```bash
if NEW_VERSION=$(php bin/bump-version.php none - -); then
    echo "no bump: ${NEW_VERSION}"
fi
```

--------------------------------

### Blade usage of registered icon sets

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/api-reference/blade-lucide-icons-service-provider.md

Blade components that render the 'lucide' and 'lucide-lab' icon sets after the service provider has registered them.

```blade
<x-lucide-activity />
<x-lucidelab-avocado />
```

--------------------------------

### SVG normalization callback in config/generation.php

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/api-reference/icon-generation.md

Defines a closure that normalizes generated SVG files by removing width and height attributes, discarding the XML declaration line, and trimming trailing whitespace. Used by both generator sets in the configuration.

```php
$svgNormalization = static function (string $tempFilepath, array $iconSet) {
    $doc = new DOMDocument();
    $doc->load($tempFilepath);
    $svgElement = $doc->getElementsByTagName('svg')[0];
    $svgElement->removeAttribute('width');
    $svgElement->removeAttribute('height');
    $doc->save($tempFilepath);

    $fileLines = file($tempFilepath);
    array_shift($fileLines);

    $lastKey = count($fileLines) - 1;
    $fileLines[$lastKey] = trim($fileLines[$lastKey]);
    file_put_contents($tempFilepath, $fileLines);
};
```

--------------------------------

### Add classes to Lucide icon component

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/README.md

Pass CSS classes to the icon component to style the rendered SVG.

```blade
<x-lucide-album class="w-6 h-6 text-gray-500"/>
```

--------------------------------

### bumpTypeFor function signature

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/api-reference/cli-detect-icon-changes.md

Determines the semantic version bump type based on added, removed, and modified icon paths. Returns 'minor' if any icons removed, 'patch' if no removals but additions/modifications, and 'none' if no changes.

```php
function bumpTypeFor(array $added, array $removed, array $modified): string
```

--------------------------------

### Add inline style to Lucide icon component

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/README.md

Apply inline styles directly to the icon component.

```blade
<x-lucide-anchor style="color: #555"/>
```

--------------------------------

### Compiled SVG output shape

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/_autodocs/api-reference/blade-icon-components.md

Shows the compiled output shape of a Blade icon component. The static attributes (viewBox, fill, stroke, stroke-width, stroke-linecap, stroke-linejoin) come from the source SVG files; width and height attributes are removed at generation time.

```xml
<?xml version="1.0"?>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
  <path d="M22 12h-2.48a2 2 0 0 0-1.93 1.46l-2.35 8.36a.25.25 0 0 1-.48 0L9.24 2.18a.25.25 0 0 0-.48 0l-2.35 8.36A2 2 0 0 1 4.49 12H2"/>
</svg>
```

--------------------------------

### Render Lucide icon component

Source: https://github.com/mallardduck/blade-lucide-icons/blob/main/README.md

Use a Lucide icon as a self-closing Blade component, which compiles to an SVG icon.

```blade
<x-lucide-activity />
```
Tokens:
Raw