---
title: "MazIcon"
description: "A flexible icon component that accepts Vue components, raw SVG strings, URLs and data URIs."
package: "maz-ui"
url: "https://maz-ui.com/components/maz-icon"
---

# MazIcon

> A flexible icon component that accepts Vue components, raw SVG strings, URLs and data URIs.

- Package: `maz-ui`
- Import: `import MazIcon from 'maz-ui/components/MazIcon'`
- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
- Web: https://maz-ui.com/components/maz-icon

**Tip:**

Download the bundled icons pack or use [`@maz-ui/icons`](../ecosystem/icons/index.md) 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. |

```vue
<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)

```vue
<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.

```vue
<MazIcon icon="/academic-cap.svg" />
```

### Vue component

```vue
<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.

```vue
<MazIcon icon="/missing.svg" :fallback="MazStar" @error="onIconError" />
```

## Sizing

### Predefined sizes (`'xs' | 'sm' | 'md' | 'lg' | 'xl'`)

```vue
<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`.

```vue
<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.

```vue
<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.

```vue
<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`:

```vue
<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:

```ts
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:

```html
<!-- 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.

Source: [Heroicons](https://heroicons.com/) - see also the [icon set page](../ecosystem/icons/icon-set.md).

## MazIcon API

`import MazIcon from 'maz-ui/components/MazIcon'`

### Props

- `icon` (`MazIconValue`): 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.
- `fallback` (`MazIconValue`, default: `MazQuestionMarkCircle`): 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.
- `size` (`MazIconSize`): Predefined keyword (`'xs' | 'sm' | 'md' | 'lg' | 'xl'`) or any CSS length.
- `title` (`string`): Sets a `<title>` element inside the SVG for screen-reader accessibility.
- `svg-attributes` (`Record<string, string | number>`): Extra attributes to merge onto the rendered `<svg>` root.
- `flip-icon-for-rtl` (`boolean`, default: `false`): Mirror the icon horizontally when the document direction is RTL. Useful for directional icons (chevrons, arrows). Renders unchanged in LTR.

### Events

- `@error` (payload: `error: Error`): Emitted when an SVG fails to fetch or parse - useful for telemetry / fallback UI.