MazIcon
A flexible icon component that accepts Vue components, raw SVG strings, URLs and data URIs.
TIP
Download the bundled icons pack or use @maz-ui/icons for the full set.
How it works
Pass an icon prop in any of the supported formats — the component detects what it received and renders accordingly:
| Input | Example | Use it for |
|---|---|---|
| Vue component | import { MazStar } from '@maz-ui/icons/static/MazStar' | Always-rendered icons that you also want available as a standalone component (<MazStar />). |
| Raw SVG string | import { MazStar } from '@maz-ui/icons/raw/MazStar' | Always-rendered icons — the lightest format, no Vue component overhead. |
URL or data: URI | '/icons/star.svg', 'data:image/svg+xml,…' | SVGs hosted in your public/ folder or external CDN. Fetched and cached on demand. |
<script setup>
import MazIcon from 'maz-ui/components/MazIcon'
import { MazStar } from '@maz-ui/icons/raw/MazStar'
</script>
<template>
<MazIcon :icon="MazStar" />
<MazIcon icon="/icons/star.svg" />
<MazIcon icon="<svg viewBox='0 0 24 24'><path d='M0 0h24v24H0z'/></svg>" />
</template>Examples
Raw SVG (recommended)
<script lang="ts" setup>
import { MazStar } from '@maz-ui/icons/raw/MazStar'
</script>
<template>
<MazIcon :icon="MazStar" />
</template>URL (fetched at runtime)
Place your SVG file in your public/ folder, then point icon to its path. The component caches the fetched payload and shares it across instances.
<MazIcon icon="/academic-cap.svg" />Vue component
<script lang="ts" setup>
import { MazStar } from '@maz-ui/icons/static/MazStar'
</script>
<template>
<MazIcon :icon="MazStar" />
</template>Fallback
When the URL fetch fails, an error event is emitted and MazIcon switches to the fallback prop (same shape as icon). If neither resolves, the bundled MazQuestionMarkCircle is rendered.
<MazIcon icon="/missing.svg" :fallback="MazStar" @error="onIconError" />Sizing
Predefined sizes ('xs' | 'sm' | 'md' | 'lg' | 'xl')
<script lang="ts" setup>
import { MazStar } from '@maz-ui/icons/raw/MazStar'
</script>
<template>
<MazIcon v-for="size in ['xs', 'sm', 'md', 'lg', 'xl']" :key="size" :size="size" :icon="MazStar" />
</template>Custom size (any CSS length)
Allowed units: px, em, rem, %, vw, vh, cm, mm, in, pt, pc, ex.
<MazIcon size="0.5em" :icon="MazStar" />
<MazIcon size="1em" :icon="MazStar" />
<MazIcon size="24px" :icon="MazStar" />
<MazIcon size="4rem" :icon="MazStar" />
<MazIcon size="8rem" :icon="MazStar" />Accessibility
By default MazIcon is rendered as decorative (aria-hidden="true", no role). Provide an aria-label (either on <MazIcon> or in svgAttributes) to expose it to assistive tech — role="img" is set automatically and aria-hidden is dropped.
<MazIcon :icon="MazStar" aria-label="Favorite" />RTL flipping
Set flip-icon-for-rtl on directional icons (chevrons, arrows). The icon is mirrored horizontally when the document direction is rtl and rendered unchanged otherwise.
<MazIcon :icon="MazChevronRight" flip-icon-for-rtl />Custom SVG attributes
Inject extra attributes onto the rendered <svg> (or onto the inlined raw SVG) via svg-attributes:
<MazIcon :icon="MazStar" :svg-attributes="{ 'data-testid': 'star', fill: 'currentColor' }" />SSR
Components, raw SVG strings and SVG data: URIs (e.g. a small ?url import inlined by Vite) are always part of the server HTML, without any request.
The server never waits for the network to render a URL icon:
- once the server has the SVG in its cache, it inlines it;
- otherwise, it renders an empty placeholder reserving the icon box and fetches the SVG in the background for the next renders. The client loads the icon in the placeholder.
A relative URL (/icons/star.svg, from your public/ directory) can only be fetched by the server with an absolute base URL, see below.
Base URL for relative URLs
Prefix every relative URL icon by providing a base URL via Vue's provide. An absolute base also lets the server fetch them:
import { createApp } from 'vue'
const app = createApp(App)
app.provide('mazIconPath', 'https://cdn.your-app.com')In Nuxt, set mazUi.general.defaultMazIconPath in nuxt.config and @maz-ui/nuxt wires the provide for you.
Forwarding MazIconProps from a consumer
Most icon-aware components in maz-ui (MazBtn, MazInput, MazLink, MazContainer, MazDropdown) accept a flexible icon prop on their startIcon, endIcon, icon or dropdownIcon slots. You can pass either a bare value (the same shape as MazIcon's icon prop) or a full MazIconProps object when you need fine-grained control:
<!-- bare value — common case -->
<MazBtn :start-icon="MazStar" />
<MazBtn start-icon="/icons/star.svg" />
<!-- full props object — override size, set a title, flip for RTL, etc. -->
<MazBtn
:start-icon="{
icon: MazStar,
size: 'xl',
title: 'Favorite',
flipIconForRtl: true,
}"
/>The consuming component still derives sensible defaults (e.g. icon size from the button's size prop), and the values you set in the props object override those defaults.
All bundled icons
This pack is the Heroicons set plus a few additions specific to maz-ui.
Download packSource: Heroicons — see also the icon set page.
Props
| Name | Description | Type | Required | Default | Possible values |
|---|---|---|---|---|---|
| icon | The icon to render. Accepts: - A Vue component (e.g. import { MazStar } from '@maz-ui/icons/static/MazStar') - A URL or data: URI to a .svg file ('/icons/star.svg', 'data:image/svg+xml,…') - A raw SVG string ('<svg viewBox="0 0 24 24">…</svg>') The component detects the format and renders accordingly. | MazIconValue | No | - | - |
| fallback | Fallback icon used when: - icon is not provided - icon is a URL that fails to load or returns invalid SVG Same shape as icon. Defaults to the imported MazQuestionMarkCircle if neither icon nor fallback resolves to anything renderable. | MazIconValue | No | MazQuestionMarkCircle | - |
| size | Predefined keyword ('xs' | 'sm' | 'md' | 'lg' | 'xl') or any CSS length. | MazIconSize | No | - | - |
| title | Sets a <title> element inside the SVG for screen-reader accessibility. | string | No | - | - |
| svg-attributes | Extra attributes to merge onto the rendered <svg> root. | Record<string, string | number> | No | - | - |
| flip-icon-for-rtl | Mirror the icon horizontally when the document direction is RTL. Useful for directional icons (chevrons, arrows). Renders unchanged in LTR. | boolean | No | false | - |
Events
| Event name | Payload | Description |
|---|---|---|
| error | error: Error | Emitted when an SVG fails to fetch or parse - useful for telemetry / fallback UI. |