Correct and idiomatic ways to use the <mds-icon> component, ordered from most common to most specialized. Patterns assume a working knowledge of the icon slug conventions documented in agents/conventions.md and the icon setup in agents/assets.md.

Icon Slug from the Shared Library

The canonical form. Pass a slug string as name; the component fetches the matching SVG from the configured assets directory. Slugs follow the convention of the active iconsauce plugin: mi/<variant>/<name> for Material Icons, mdi/<name> for Material Design Icons, and mgg/<name> for the internal Maggioli set.

<!-- Material Icons baseline variant -->
<mds-icon name="mi/baseline/search"></mds-icon>

<!-- Material Design Icons -->
<mds-icon name="mdi/alien"></mds-icon>

<!-- Internal Maggioli set -->
<mds-icon name="mgg/action-email-send-wait"></mds-icon>

Configuring the SVG Base Path via IconsSetService (recommended)

Import the shared IconsSetService singleton from the package’s services entry point and call setSvgPath(). It updates the shared, in-memory icon path - kept on globalThis so every bundled copy of the service (lazy chunks, esm/esm-es5 variants, dist/components) agrees on it - and notifies all mounted icons to (re)load immediately. No sessionStorage is involved, which makes it the safest option when storage is blocked (incognito, sandboxed iframes, storage partitioning). Pass an absolute path (starting with /) or a full URL. The icons are downloaded with fetch: under a Content Security Policy the origin of the path must be allowed by connect-src (or default-src), which 'self' already does for a path on the page’s own origin, while a CDN must be listed.

import { IconsSetService } from '@maggioli-design-system/magma/services';

IconsSetService.setSvgPath('/assets/img/svg/');

It can be called before or after the icons mount: instances mounted earlier re-fetch automatically once the path is set. Always use the exported IconsSetService; do not construct your own controller, which would keep a separate icon cache and listener list.

Configuring the SVG Base Path via sessionStorage (optional)

Set mdsIconSvgPath in sessionStorage before any <mds-icon> mounts; every icon instance falls back to this key when no path has been set programmatically. This one-liner is convenient but may be blocked by some browsers, privacy/incognito modes, storage partitioning, or sandboxed iframes - when that happens, use IconsSetService.setSvgPath() above instead.

window.sessionStorage.setItem('mdsIconSvgPath', '/assets/img/svg/');

Forcing a Reload After Late Path Configuration

If icons are already in the DOM when the SVG path is set (for example, inside a lazy-loaded module), dispatch mdsIconSvgPathUpdate after configuring the path. Every mounted instance listens for this event and re-fetches.

window.sessionStorage.setItem('mdsIconSvgPath', '/assets/img/svg/');
window.dispatchEvent(new CustomEvent('mdsIconSvgPathUpdate'));

Configuring the SVG Base Path via the Instance Method

An alternative to IconsSetService when you already hold an <mds-icon> element: call its setSvgPath @Method. It delegates to the same singleton, so the effect is identical - prefer IconsSetService unless creating an element is more convenient (for example, in isolated testing environments).

await customElements.whenDefined('mds-icon');
const tmp = document.createElement('mds-icon');
document.body.appendChild(tmp);
if ('setSvgPath' in tmp) {
  tmp.setSvgPath('/assets/img/svg/');
}
document.body.removeChild(tmp);

Inline Raw SVG String

Pass a full SVG markup string as name when the artwork is generated or received at runtime and does not have a slug in the library. The component uses the string verbatim - no network request is made.

<mds-icon
  name='<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 2L2 22h20L12 2z"/></svg>'
></mds-icon>

Base64-encoded SVG Data URI

Pass a data:image/svg+xml;base64,... string when the icon is delivered from an API as a Base64 payload. The component decodes it inline - no external fetch occurs. In the current release only the first = of the padding is stripped, so a payload ending in == fails to decode: strip the padding before passing it.

<mds-icon name="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZD0iTTEyIDJMMiAyMmgyMHoiLz48L3N2Zz4="></mds-icon>

Sizing via CSS Width

<mds-icon> is display: inline-flex with aspect-ratio: 1 and a default width of --spacing(600). Override size by setting a width on the host - height scales automatically via the aspect ratio. Use Magma spacing tokens to stay on-grid.

<!-- Small icon using a Tailwind spacing utility -->
<mds-icon name="mi/baseline/info" class="w-400"></mds-icon>

<!-- Large icon -->
<mds-icon name="mi/baseline/star" class="w-1200"></mds-icon>

Coloring via fill Utility or currentColor

The inlined SVG paints with the inherited CSS fill, so a Tailwind fill-* utility on the host, or fill: currentColor on a parent to follow its text color, is enough to tint the artwork; color alone does not tint it. Use Magma color roles, or a label-* colour for a category.

<!-- Tint with a Magma label token -->
<mds-icon name="mi/baseline/check-circle" class="fill-label-green-06"></mds-icon>

<!-- Follow the current text color of a parent -->
<p class="text-success-fg fill-current">
  <mds-icon name="mi/baseline/check"></mds-icon>
  Operazione completata
</p>

Standalone Decorative Icon Inside a Labelled Control

<mds-icon> renders with aria-hidden="true" on its inner element; it carries no accessible name itself. When used standalone next to visible text, no extra ARIA is needed. When used as the only visual indicator inside an interactive control, the control must supply the accessible name.

<!-- Decorative: the adjacent text provides the meaning -->
<span class="flex items-center gap-200">
  <mds-icon name="mi/baseline/email"></mds-icon>
  Invia messaggio
</span>

Styling via ::part(svg)

The single documented shadow part is svg - the <i> wrapper around the inlined SVG. Use ::part(svg) only for deep SVG styling not achievable through fill or color. Keep to documented parts; undocumented internals can change on minor releases.

mds-icon::part(svg) {
  filter: drop-shadow(0 1px 2px rgb(var(--magma-shadow-ink) / 0.3));
}