Tabler Ux Components Laravel Package

Getting Started

This is a Symfony UX / Twig Components package (not Blade), so day-to-day use is in Twig templates via <twig:Tabler:...>. Laravel developers can still adopt the icon-naming conventions and the underlying Tabler markup, but the components themselves assume Symfony UX + Twig Components.

1. composer require silarhi/tabler-ux-components
2. Make sure the Tabler CSS/JS (webfont) is loaded in your layout — via AssetMapper/Webpack Encore as you normally do for Tabler.
3. Render your first icon:

<twig:Tabler:Icon name="check" />

4. New in 0.8.0 — to render any icon set as inline SVG, add the optional dependency: composer require symfony/ux-icons, enable the sets you want (lucide, mdi, tabler, …) in your UX Icons config, then use a prefixed name:

<twig:Tabler:Icon name="lucide:circle-check" />

First use case: take one existing page that uses the webfont, swap a single icon (e.g. a status badge) to lucide:circle-check, and confirm the DOM changes from a webfont <i>/class-based element to an inline <svg> while variant/size/animation styling stays identical. That one-swap test tells you whether your CSS targets markup or classes.

Implementation Patterns

Two rendering modes, one prop. The name prop decides the mode:

• No prefix → Tabler webfont (unchanged from 0.7.x).
• set:name → inline <svg> via Symfony UX Icons, keeping Tabler's icon class plus the same variant, size and animation classes.

Every icon prop accepts prefixed names. Buttons, alerts, cards, nav items, etc. all take lucide:.../mdi:.../tabler:... wherever they took a bare Tabler name. This is the main integration win: you can standardise on one icon set without dropping the component API.

Filled icons. <twig:Tabler:Icon name="check" filled /> resolves to tabler:check-filled in the tabler set. Treat filled as a Tabler-set shorthand rather than a generic "solid variant" switch — it does not magically find a filled equivalent in other sets.

Mixed-mode strategy. A pragmatic split:

• Inline SVG (prefixed) for icons Tabler doesn't have, for strict-CSP setups, and to avoid webfont FOUT.
• Webfont (unprefixed) for high-frequency chrome where repeated inline <svg> markup bloats HTML.

Enforce a convention in one place. Wrap the component in a project-level icon component/macro that owns the set prefix, so refactoring from tabler: to lucide: is a one-file change instead of a grep across templates.

Keep the upgrade cheap. Because size/variant/animation classes are identical across both modes, you can migrate icon-by-icon per template rather than in a big-bang PR.

Testing. Assert on what you actually care about: <svg present for prefixed names, webfont markup for unprefixed ones. Any snapshot/DOM assertions written against 0.7.x output will need refreshing.

Gotchas and Tips

• symfony/ux-icons is only suggested. Prefixed names will fail (or fall back unexpectedly) if it isn't installed and configured. Add it to CI so a missing icon set fails loudly rather than shipping broken icons.
• The upgrade is non-breaking only if you use unprefixed names. 0.8.0 changes the DOM for every prefixed name — audit CSS selectors and JS that target webfont markup before rolling out.
• Bump @tabler/icons-webfont to 3.36.1+. The release explicitly fixes the Symfony UX Toolkit kit, which previously allowed 3.0+. Versions before 3.36.1 lack the filled icons that <twig:Tabler:Icon filled> needs, so filled renders empty/404s. Rebuild your importmap or assets after bumping.
• filled is Tabler-set-specific. It maps to tabler:{name}-filled; don't assume lucide:circle-check + filled produces a solid Lucide icon.
• Names without a prefix still use the webfont. Silent inconsistency is the most likely long-term mess — decide early whether a given component tree is webfont-first or SVG-first.
• Debugging prefixed icons: dump the rendered HTML first, then verify the icon set is enabled/installed in UX Icons config, then bin/console cache:clear and rebuild asset maps. Most failures are configuration, not the component.
• Payload awareness. Inline SVG duplicates markup on every render; for an icon repeated dozens of times per page, the webfont (or a sprite/cached ux_icon approach) is still cheaper.
• Extension points: override the bundle's Twig templates under templates/bundles/... for markup changes, register custom icon sets through UX Icons config, and wrap the component for project-wide naming/ARIA defaults. Add your own aria-hidden/label handling in that wrapper — icon accessibility semantics are the caller's responsibility.
• Version skew: keep the PHP package and the Tabler webfont JS/CSS versions in lockstep; the 0.8.0 fix is exactly the kind of breakage that appears when they drift.