Icon

The built-in icon tag — a Mantine ThemeIcon you can drop inline in prose or a heading. Render a Tabler glyph, a Font Awesome glyph, an image, or an emoji, with the full ThemeIcon surface (variant, color, size, radius, gradient) and a tooltip on hover.

A built-in inline tag for dropping an icon inside text — a sentence, a list item, or a heading. It renders a Mantine ThemeIcon, so it carries the whole ThemeIcon surface — variant, color, size, radius, gradient — while still flowing inline. By default it’s a bare glyph that inherits the surrounding text’s size and color; add a variant/color to turn it into a Mantine icon chip. Use it as {% icon "rocket" %} in Markdown, or call it from Python logic (loops, snippets) via component('aardvark', 'icon', 'rocket', …).

The first argument is the icon, quoted. It can be a Tabler name (a bare lowercase name like rocket or brand-github), a Font Awesome class (fa-solid fa-rocket, fab fa-github), a path/URL to an SVG or image file (/icons/folder.svg), or an emoji (🚀).

Demonstrations

Inline glyphs

A bare name renders an inline glyph that inherits the surrounding text’s size and color:

Launch it when you’re ready, then star it on GitHub .

Variants and colors

Pass any Mantine ThemeIcon variant — filled, light, outline, transparent (the default), white, default, or gradient — with a color to turn the bare glyph into a chip. A gradient variant reads gradientFrom/gradientTo/gradientDeg:

color is a Mantine color name (blue, pink, …) or any CSS color. autoContrast flips the glyph between light/dark for legibility on its background.

Size and radius

size takes a Mantine size (xs–xl) or a number of pixels; radius takes a Mantine radius (xs–xl) or a number:

With no size, the icon is 1em and tracks the surrounding text — so a bare icon grows with whatever it sits in, including headings:

Ship faster

Built for teams

Nudging and spacing

A glyph sometimes sits a hair high or low for your text, or you want a little space around it. Use Mantine’s margin/padding style props — mt/mb/ml/mr (or the mx/my/m shorthands) for margin, and pt/pb/… (or px/py/p) for padding. A bare number is pixels, and negatives nudge:

Lift it up, drop it down, or space it out.

A named Mantine spacing works too (mt="xs"), and these apply to every variant.

Tooltip and accessible name

Give an icon a label and hovering (or focusing) it shows a Mantine Tooltip with that text. The label is also the icon’s accessible name (it sets aria-label) and makes the icon keyboard-focusable, so the tooltip works without a mouse and a screen-reader user hears the name too. Use it when a standalone icon is the meaning and nothing adjacent already says it:

Icons without a label are decorative — they’re hidden from assistive tech (aria-hidden), and the surrounding text carries the meaning.

Don’t label an icon that’s the content of a link or button. A labelled icon is its own keyboard focus stop, so wrapping one in an <a>/<button> makes a second tab stop and a doubled screen-reader announcement. Leave the icon decorative (no label) and put the accessible name on the outer element instead — name the link, not the icon:

Tabler, Font Awesome, image, and emoji

A bare name is a Tabler icon — there are over 5,800. Tabler ships an outline style by default and a filled style for many icons; add the filled flag for the filled variant. A Font Awesome glyph needs its full class (the style class fa-solid/fa-regular/fab/… plus the icon class) and the FA stylesheet (theme.fontawesome: true in aardvark.config.yaml, which this site sets). A path or URL ending in .svg/.png/.webp/… renders as an inline <img>, and a non-ASCII glyph renders as an emoji:

outline, filled — — open the folder, or just 🚀 ship it.

A bare rocket is the Tabler rocket, so Font Awesome always needs its fa-… class. Image and emoji icons keep their own colors — the color override tints a Tabler or Font Awesome glyph only.

With other components

An icon flows inline inside any other component — here it leads a {% badge %} and labels a {% card %}:

Loading and the CDN

The {% icon %} tag is a Mantine island, so it needs the islands bundle (which this site builds). Tabler glyphs add one more step: the first time a page uses a Tabler icon, aardvark fetches its SVG from a pinned jsDelivr CDN (cdn.jsdelivr.net), caches it per name, and injects it inline — only the icons a page actually uses are fetched.

Because that fetch is client-side, a Tabler glyph renders only after the page’s JavaScript runs: the build’s server-side prerender bakes an empty reserved box (no layout shift), and the glyph pops in on mount. Font Awesome, image, and emoji icons are baked into the prerendered HTML and show with no JavaScript. So a site that must render icons without JS (or before hydration) should prefer Font Awesome or image icons over Tabler.

Navigation icon: and heading-icon: values are latency-sensitive page chrome, so Aardvark special-cases them: their SVGs are baked into the initial HTML and paint immediately — from the outline set bundled with aardvark (so it works even with no local @tabler/icons install, e.g. a pip/binary site), or from the installed package when it matches a pinned theme.iconVersion. A custom theme.iconCdn stays authoritative — navigation keeps its runtime loader and vark build emits no warning. A pinned theme.iconVersion that’s neither bundled nor installed also falls back to the runtime loader, and there vark build warns which glyphs it couldn’t bake.

If your site sets a Content-Security-Policy, allow the CDN origin in connect-src (the fetch). To self-host the icons or pin a different release, set one of these in aardvark.config.yaml:

• theme.iconCdn — a full http(s) base that serves <base>/outline/<name>.svg (and <base>/filled/<name>.svg);
• theme.iconVersion — a bare X.Y.Z to pin the default jsDelivr package version.

Attributes

A bare name (no fa-… class, no file extension, ASCII) is read as a Tabler icon — if it isn’t a real Tabler name, the loader logs a console warning and leaves the slot empty, so check the name at tabler.io/icons. Keep {% icon %} on the same line as adjacent text: an icon alone on its own line is treated as a block, not an inline glyph.

CSS Selectors

Target the rendered element through its island marker — [data-aardvark-island="Icon"] — or through the Mantine Styles API classes (.mantine-ThemeIcon-root and its inner parts):

/* Every rendered Icon carries this island marker */
[data-aardvark-island="Icon"] { }

/* Mantine Styles API class on the root element */
.mantine-ThemeIcon-root { }

Injecting Attributes

attr={…} forwards raw HTML attributes — id, data-*, ARIA, analytics hooks, or an inline event handler — onto the rendered icon. (For the icon’s own surface — variant, color, size, radius, gradient, and label for its accessible name and hover tooltip — use the documented props above.)