Twigeasy_svg_icon()

easy_svg_icon()

Draw a stored icon as inline SVG in a Timber or Twig template, with an accessible label or as decoration, from any collection on the site.

Twig function · Easy SVG Pro · Status: Stable

Timber themes write their markup in Twig, where PHP functions are not available. This Twig function brings the free plugin's icon renderer into your templates: name an icon by its address, and the inline SVG appears, already sanitized. It works for every collection the site has, from the free library to Pro icon sets and theme folders.

Usage

{{ easy_svg_icon( 'collection/slug' ) }}
{{ easy_svg_icon( 'collection/slug', { class: '', label: '', decorative: true } ) }}

Registered in includes/twig/twig.php on the timber/twig filter. Available since Easy SVG Pro 1.7.0.

When to use it

  • Your theme is built with Timber 1 or Timber 2 and you want icons in .twig files.
  • You want inline SVG that inherits currentColor and can be styled with CSS, not an img tag.
  • You need the same accessibility rules as easy_svg_icon() in PHP: decorative by default, named when you pass a label.

Do not use it when:

  • The icon address comes from a field and you prefer a pipe. The filter form does the same.
  • You only want to know whether an icon exists. Use easy_svg_icon_exists().
  • Your template is plain PHP. Call easy_svg_icon() from the free plugin directly.

Parameters

body
namestring
Required

The icon address. Either collection/slug, for example acme/phone, or a bare slug such as phone, which means the free icon library (easy-svg/phone). Anything that is not a string, or an empty string, prints nothing.

body
argshash

A Twig hash with up to three keys, handed to the free plugin's easy_svg_icon():

  • class: added as a class attribute on the root svg element.
  • label: makes the icon meaningful. It gets role="img" and aria-label with this text.
  • decorative: true hides the icon from screen readers (aria-hidden="true"), false keeps it meaningful even without a label.

Anything that is not a hash, for example a string, is ignored and treated as no arguments.

Return value

returnstring

The icon's inline SVG markup, marked safe for HTML so Twig prints it as markup and not as text. An empty string when the icon does not exist, the name is empty, or the free plugin is too old to have easy_svg_icon().

Default

Without args the icon is decorative: aria-hidden="true" focusable="false" are added to the root svg, and no class.

Examples

A decorative icon next to text

<a class="contact-link" href="tel:+4930123456">
	{{ easy_svg_icon( 'acme/phone', { class: 'contact-link__icon' } ) }}
	Call us
</a>

The text says what the link does, so the icon stays hidden from screen readers.

An icon that carries meaning on its own

<button class="menu-toggle" aria-expanded="false">
	{{ easy_svg_icon( 'acme/menu', { label: __( 'Open menu', 'acme' ) } ) }}
</button>

Timber exposes __() in Twig, so the label is translated. The SVG gets role="img" and aria-label="Open menu".

Agency: one partial for every icon in a component library

{# templates/partials/icon.twig #}
{% set icon_classes = 'c-icon' ~ ( size is defined and size ? ' c-icon--' ~ size : '' ) %}
{{ easy_svg_icon( name, { class: icon_classes, label: label|default( '' ) } ) }}

{% include 'partials/icon.twig' with { name: 'acme/arrow-right', size: 'sm' } only %}
{% include 'partials/icon.twig' with { name: 'acme/warning', label: 'Warning' } only %}

All icon markup in the theme goes through one file. If you later change classes or switch collections, you change it there.

Defensive: a fallback when the icon is missing

{% set icon %}{{ easy_svg_icon( 'acme/' ~ service.slug ) }}{% endset %}
{% if icon|trim is not empty %}
	{{ icon }}
{% else %}
	{{ easy_svg_icon( 'acme/generic-service' ) }}
{% endif %}

The set block captures the output as safe markup, so {{ icon }} prints the SVG. The icon is rendered once, not twice as with easy_svg_icon_exists() followed by easy_svg_icon().

How it works

  1. On init Easy SVG Pro checks the licence and the Timber / Twig feature under Icons → Features. Only if both are on does it hook timber/twig. Both Timber 1 and Timber 2 apply that filter when they build their Twig environment.
  2. When Timber builds the environment, the function is added with is_safe: ['html']. If the environment has no addFunction() or the \Twig\TwigFunction class is missing, nothing is added.
  3. On every call the name and the hash are passed to the free plugin's easy_svg_icon(). That function splits the address, looks up the markup through the easy_svg_icon_markup filter (where Pro serves its sets and folder collections) and adds the accessibility attributes.
  4. The markup returned is the stored, sanitized and hardened markup. If Styles & theme colors is on, its templates and colour mapping are already applied.

There is no second renderer: Twig, PHP templates, shortcodes and the Icon block all draw the same markup.

Pitfalls

  • Feature off means a broken template, not an empty icon. If the licence lapses or someone turns off Timber / Twig, the function is not registered at all, and Twig stops with an "Unknown function" error when it compiles the template. "Prints nothing" only applies while the function is registered. If you cannot be sure the feature stays on, see the defensive pattern on the Timber and Twig tutorial.
  • Assigning loses the safe flag. {% set icon = easy_svg_icon( 'acme/phone' ) %} stores a plain string, and {{ icon }} then prints the SVG source as text. Use the set block form from the last example, or {{ icon|raw }}.
  • Not inside attributes. The output is marked safe for HTML only. Inside an attribute or a script block Twig escapes it, and an SVG does not belong there anyway.
  • Bare slugs mean the free library. easy_svg_icon( 'phone' ) looks in easy-svg, not in your set. Always write collection/slug for Pro collections.
  • Set slugs can differ from the post slug. On sites that ran older versions a set's collection may be acme-x. Copy the address from the Icon Sets tab, which shows the registered slug.
  • Template caches keep old output. If you cache rendered templates (Timber::render() with an expiry, or a page cache), a changed icon appears only after that cache expires.
Was this page helpful?