Blade Maki Icons Laravel Package

Getting Started

Install and confirm registration.

composer require codeat3/blade-maki-icons

Laravel package auto-discovery registers the service provider; there is no publish step and no config file to manage. Verify registration before writing templates:

php artisan about            # provider list
composer show codeat3/blade-maki-icons

Render your first icon. Components are prefixed maki and named after the upstream Maki glyph in kebab-case:

<x-maki-restaurant class="size-5 text-slate-600" />
<x-maki-fuel class="size-5 text-amber-600" />
<x-maki-lodging class="size-5 text-slate-600" />

Icons are inline SVG that inherit currentColor, so sizing and colour are ordinary Tailwind/CSS concerns — there is no color prop to learn and no build step.

Where to look first. Do not guess names. Inspect the shipped set once:

ls vendor/codeat3/blade-maki-icons/resources/svg | head -50
ls vendor/codeat3/blade-maki-icons/src/Components | wc -l

That directory listing is the API surface. Copy the relevant names into your own allowlist (see below) rather than remembering them.

First use case. A store/venue locator or POI legend: a small config/poi.php mapping your domain's place types to Maki names, rendered in a loop. That exercises the real integration shape — data-driven component names, sizing, colour, and accessibility — inside one ticket.

Implementation Patterns

Direct use for static chrome. For a handful of known markers, write the component literally. It reads better in review and greps cleanly:

<li class="flex items-center gap-2">
    <x-maki-pharmacy class="size-4 shrink-0 text-emerald-600" aria-hidden="true" />
    <span>Pharmacy</span>
</li>

Dynamic rendering for data-driven surfaces. When the icon depends on a database value (place type, delivery status, vehicle class), resolve the component at runtime:

@php
    $icon = config("poi.icons.{$place->type}", 'marker');
@endphp

<x-dynamic-component :component="'maki-'.$icon" class="size-5 text-slate-500" aria-hidden="true" />

Keep the mapping in config, never inline in a view. It doubles as the allowlist you assert against in tests and as the single place to swap icon sets later.

Wrap it once, immediately. Before the prefix spreads across fifty files, put a thin internal component in front of it:

{{-- resources/views/components/icon/maki.blade.php --}}
@props(['name', 'size' => 'size-4'])

<x-dynamic-component
    :component="'maki-'.$name"
    {{ $attributes->class([$size, 'shrink-0']) }}
    aria-hidden="true"
/>

This is where you own defaults, accessibility policy, and the eventual swap. Retrofitting this abstraction after adoption negates most of the payoff.

Sizing. Maki is drawn on a small square grid, so the aspect ratio is 1:1 — size-4 / size-5 / size-6 are the right tool. Prefer utility classes over width/height attributes so one token controls both dimensions and you cannot accidentally stretch an icon.

Colour. Style with text-* (or any color) and let currentColor flow through. Tint by context — status colours for delivery states, muted neutrals for legend markers, brand colour on the active marker.

Accessibility. The wrapper above marks everything decorative by default. For a marker that carries meaning on its own, render a label rather than relying on the glyph:

<span class="inline-flex items-center gap-1">
    <x-maki-wheelchair class="size-4" aria-hidden="true" />
    <span class="sr-only">Wheelchair accessible</span>
</span>

You cannot inject a <title> into the generated SVG through attributes, so the adjacent-text pattern is the reliable route.

Livewire and Inertia. Both work unchanged — these are server-rendered Blade components with no JavaScript and no hydration surface. In Livewire, re-renders re-emit the SVG, so keep the wrapper cheap and avoid computing the icon name in the render method when a computed property or config lookup will do.

Testing. Two tests earn their keep:

it('renders every configured poi icon', function () {
    foreach (config('poi.icons') as $icon) {
        $this->blade("<x-maki-{$icon} />")->assertSee('<svg', false);
    }
});

Plus a snapshot/assertSee on an icon-heavy page to catch silent glyph drift when the package is bumped. Add php artisan view:cache to CI — it compiles all Blade templates and surfaces registration or syntax problems before deploy.

Caching. Check whether the icon-cache command is available in your app (php artisan list | grep -i icons). If it is, run it as part of the deploy sequence alongside view:cache; if not, view:cache alone still collapses the per-render Blade compilation cost. Measure an icon-heavy screen before optimising further.

Gotchas and Tips

Unknown names fail loudly and unhelpfully. A typo in a dynamic component name throws Unable to locate a class or view for component [maki-xyz] at render time — possibly in production, on the one place type nobody seeded in staging. The config-mapping plus the loop test above is the mitigation; treat the config file as the validated contract.

Don't let it become the general icon set. Maki is a Mapbox-originated POI/map vocabulary. It has no meaningful coverage of navigation, form controls, media, or chevrons. The moment someone reaches for <x-maki-...> in a sidebar nav, you have started a second icon library. Sanction it explicitly for map, geolocation, and logistics surfaces, and keep a general UI set alongside it deliberately rather than by accident.

Icon art changes between releases. The wrapper is thin but the SVGs are the payload — a minor bump can alter glyph geometry. Pin the constraint (^1.10 plus a committed lock file), read the changelog on every bump, and lean on your snapshot test. Note that 1.10.0 was a compatibility-only release widening the framework constraint for Laravel 13 — no API changes, no renamed components — so it is a safe bump and, if you are mid-upgrade, the unblocker rather than an optional one.

The Laravel 13 bump only helps if the rest of the graph cooperates. Run a dry resolve before committing to an upgrade date:

composer why-not laravel/framework ^13.0

One other package pinning illuminate/support to ^11/^12 defeats this release regardless. Also confirm your PHP floor matches Laravel 13's requirement.

Some glyphs may resist text-*. If an icon refuses to take the colour, open the shipped SVG and check for a hardcoded fill or stroke. Work around it at the wrapper with a descendant selector rather than editing vendor files:

<x-maki-foo class="size-5 text-slate-600 [&_*]:fill-current [&_*]:stroke-current" />

Component name collisions are prefix-scoped but not impossible. If your design system already reserves the maki prefix, or you register another icon package with bare names, collisions surface as "the wrong icon renders" rather than an exception. php artisan view:clear plus a quick Blade::getClassComponentAliases() dump is the fastest way to see what actually won.

Component not rendering at all? In order: composer dump-autoload, php artisan view:clear, then check php artisan about for the provider. Almost every "it's not installed" report is stale compiled views or a cached config from a deploy.

Zero stars and zero dependents are not a quality signal here. This is a generated wrapper around a well-known open-source set, maintained by one person. The exit is structural, not contractual: the entire payload is static SVG files, so vendoring the icon directory or forking the wrapper is a days-scale job. Write that fallback down (which directory, who owns it) while adoption is cheap — and keep your internal wrapper component as the seam that makes it a one-file change.

Extension points are limited by design. There is no meaningful config surface and no view to publish — the wrapper component is your extension point. If you need brand-restyled map glyphs, Maki cannot give them to you; that is a separate design investment, not a package configuration.