Icon
Accessible, unstyled SVG icon primitive.
| Package | @vizejs/ui/icon |
| Maturity | stable |
| Own the source | vize lib pull icon |
| Requires | id |
| Aliases | svg icon, glyph, pictogram, icon composer |
| Covers | SVG title element, SVG desc element, React Aria SVG semantics |
Minimal setup
Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).
vp install @vizejs/ui
Add the public import below to <script setup lang="ts">. Components provide behavior without styles; the preview uses optional Paper styles.
import { Icon } from "@vizejs/ui/icon";
Or copy the source into your project with vize lib pull icon (see Source Distribution).
Try it
This is the basic example maintained with the component source, using the public package imports. The preview adds the optional Paper styles.
Open the interactive example · Styling these components
Copy the example
<!-- Meaningful SVG icon named by its title next to a decorative icon hidden from assistive technology. -->
<script setup lang="ts">
import { Icon } from "@vizejs/ui/icon";
</script>
<template>
<p>
<Icon title="Warning" size="sm">
<path d="M12 3 2 21h20L12 3Z" />
<path d="M12 10v5" />
<path d="M12 18h.01" />
</Icon>
Your trial ends in three days.
</p>
<p>
<Icon aria-hidden>
<path d="M5 12h14" />
<path d="m13 6 6 6-6 6" />
</Icon>
Continue to billing
</p>
</template>
API
Icon
Source: src/families/layout/icon/icon.vue
Props
| Prop | Type | Default | Description |
|---|---|---|---|
as |
PrimitiveAs |
"svg" |
SVG element, custom element, or component to render as the root. |
id |
string |
undefined |
Consumer-owned root id. Missing ids are not generated for decorative icons. |
viewBox |
string |
"0 0 24 24" |
SVG viewport. |
width |
string | number |
"1em" |
Native SVG width attribute. |
height |
string | number |
"1em" |
Native SVG height attribute. |
size |
IconSize |
"md" |
Consumer styling token mirrored to data-size. |
focusable |
boolean |
false |
Native SVG focusability. |
fill |
IconPaint |
"none" |
Root fill attribute. |
stroke |
IconPaint |
"currentColor" |
Root stroke attribute. |
strokeWidth |
IconStrokeWidth |
"2" |
Root stroke-width attribute. |
strokeLinecap |
IconStrokeLinecap |
"round" |
Root stroke-linecap attribute. |
strokeLinejoin |
IconStrokeLinejoin |
"round" |
Root stroke-linejoin attribute. |
decorative |
true | false |
true when no accessible name is provided |
Treat the icon as decorative. Icons with no accessible name are decorative by default. |
ariaHidden |
true | false |
true when no accessible name is provided |
Force the root out of the accessibility tree. |
ariaLabel |
string |
undefined |
Direct accessible name. |
ariaLabelledby |
string |
undefined |
|
ariaDescribedby |
string |
undefined |
Element ids that describe the icon. |
title |
string |
undefined |
|
description |
string |
undefined |
Inline SVG description. |
titleId |
string |
undefined |
Consumer-owned id for the generated title element. |
descriptionId |
string |
undefined |
Consumer-owned id for the generated desc element. |
Slots
| Slot | Slot props | Description |
|---|---|---|
default |
IconSlotState |
Renders SVG child nodes with current accessibility and styling hooks. |
Exposed
| Member | Type | Description |
|---|---|---|
ariaState |
IconAriaState |
|
decorative |
boolean |
|
descriptionId |
string | undefined |
|
size |
IconSize |
|
titleId |
string | undefined |
|
viewBox |
string |
|
element |
IconElement | null |
Behavior
| Case | Required behavior |
|---|---|
icon.vue source |
Owns the canonical Icon SFC implementation and every row in this table. |
| Default icon | Renders a native svg root with data-vize-ui="icon", part="root", no class/style output, focusable="false", and decorative semantics. |
| Decorative semantics | Icons without an accessible name, or icons with decorative/ariaHidden, set aria-hidden="true" and omit role, labels, title, and desc. |
| Accessible image | Icons named by ariaLabel, ariaLabelledby, or title render role="img" and expose deterministic title/desc ids when inline text is used. |
| SVG composition | Consumers own paths through the default slot; the slot receives current ariaState, decorative, size, titleId, descriptionId, and viewBox. |
| Styling hooks | size, fill, stroke, strokeWidth, strokeLinecap, and strokeLinejoin are typed and mirrored to native SVG attributes or data-*; no CSS is emitted. |
| SSR and hydration | Generated title and description ids are deterministic across isolated SSR requests and hydrate without replacing the root. |