Skip to main content
Version: next

SVG Icons

The SVG icons feature allows you to add SVG icon assets to your project and embed them anywhere in your theme Liquid.

Icons should be placed in assets/icons/, for example assets/icons/cart.svg:

assets/icons/cart.svg
html
<svg>
    ...
</svg>
assets/icons/cart.svg
html
<svg>
    ...
</svg>
SVG icons are compiled assets

SVG icons are placed in a subdirectory of the assets/ folder at the root of your project - not inside of static/assets/!

The {! icon !} macro​

To include an icon in Liquid, use the {! icon !} macro with the icon name:

static/snippets/example.liquid
html
<span>
    Cart
    {! icon 'cart' !}
</span>
static/snippets/example.liquid
html
<span>
    Cart
    {! icon 'cart' !}
</span>
dist/snippets/example.liquid
html
<span>
    Cart
    <svg>
        ...
    </svg>
</span>
dist/snippets/example.liquid
html
<span>
    Cart
    <svg>
        ...
    </svg>
</span>

You can use the {! icon !} macro in any static Liquid file (static/**/*.liquid), as well as in component templates.

Working with currentColor​

Any fill or stroke colors in your SVG icons are automatically converted to currentColor. This means your icons will inherit the text color of their container (i.e. color in CSS.)

This allows you to reuse icons without needing extra versions for each possible color:

Using SVG icons with currentColor
html
This is a black icon:
<span style="color: black">
    {! icon 'circle' !}
</span>
<br>
This is a red icon:
<span style="color: red">
    {! icon 'circle' !}
</span>
Using SVG icons with currentColor
html
This is a black icon:
<span style="color: black">
    {! icon 'circle' !}
</span>
<br>
This is a red icon:
<span style="color: red">
    {! icon 'circle' !}
</span>

If you're not using monotone icons or you want more control over which elements of your icons use currentColor, you can disable this feature by setting optimizations.icons.convertToCurrentColor to false:

Using SVG icons with hard-coded colors
html
This is a black icon:
<span>
    {! icon 'circle-black' !}
</span>
<br>
This is a red icon:
<span>
    {! icon 'circle-red' !}
</span>
Using SVG icons with hard-coded colors
html
This is a black icon:
<span>
    {! icon 'circle-black' !}
</span>
<br>
This is a red icon:
<span>
    {! icon 'circle-red' !}
</span>

Including class names and extra attributes​

You can specify a classname or additional attributes to inject on to the <svg> element by passing them as arguments to the {! icon !} macro:

Providing a classname
html
{! icon 'circle', class: 'icon icon-large' !}
Providing a classname
html
{! icon 'circle', class: 'icon icon-large' !}
Providing extra attributes
html
{! icon 'circle', role: 'img', aria-label: 'This is the circle icon' !}
Providing extra attributes
html
{! icon 'circle', role: 'img', aria-label: 'This is the circle icon' !}

Classnames will be appended to any existing classnames in the original SVG. Other attributes will just be added to the end of the element.

caution

You cannot use a Liquid variable as an argument to the {! icon !} macro. Macros are resolved at compile-time, so only static strings are supported.