Skip to content

OrigamIcon ​

<OrigamIcon> is the polymorphic dispatcher at the heart of the icon family. It receives any of the supported icon notations and renders the matching leaf component automatically:

Input shapeResolves toRendered as
'mdi:mdi-home' (set-prefixed string)OrigamClassIcon (via the registered set)<i class="mdi mdi-home">
'mdi-home' (default-set fallback)OrigamClassIcon<i class="mdi mdi-home">
'$success' (alias)OrigamClassIcon (alias resolved)<i class="mdi mdi-check-circle">
'M12 …' (single SVG path)OrigamSvgIconinline <svg><path d>
[...] (array of paths)OrigamSvgIconinline <svg> with multiple <path>
Vue component (e.g. lucide / hugeicons)OrigamComponentIconwrapper <div> + inner component

OrigamIcon is also the only place the icon mixin set is wired (useBothColor, useBorder, usePadding, useMargin, useSize). The leaf components only carry sizing (numeric override + named class).

Basic usage ​

vue
<template>
    <!-- Material Design Icons font set (default) -->
    <OrigamIcon icon="mdi-heart" />

    <!-- Explicit set prefix -->
    <OrigamIcon icon="mdi:mdi-account" />

    <!-- Aliased icon -->
    <OrigamIcon icon="$success" />

    <!-- Inline SVG path -->
    <OrigamIcon icon="M12 2 L17 8 …" />

    <!-- Vue component icon -->
    <OrigamIcon :icon="LucideHomeIcon" />
</template>

Sizes ​

Five named tiers are mapped to the typographic scale tokens:

vue
<template>
    <OrigamIcon icon="mdi-home" size="x-small" />  <!-- --origam-icon---font-size-xs -->
    <OrigamIcon icon="mdi-home" size="small"   />  <!-- --origam-icon---font-size-sm -->
    <OrigamIcon icon="mdi-home" size="default" />  <!-- --origam-icon---font-size-md -->
    <OrigamIcon icon="mdi-home" size="large"   />  <!-- --origam-icon---font-size-lg -->
    <OrigamIcon icon="mdi-home" size="x-large" />  <!-- --origam-icon---font-size-xl -->

    <!-- Numeric override (pixels) -->
    <OrigamIcon icon="mdi-home" :size="48" />
</template>

Color (intent) ​

Icons inherit currentColor by default — set the color on any ancestor and the icon picks it up. For an explicit override, use color / bgColor:

vue
<template>
    <OrigamIcon icon="mdi-alert"   color="danger" />
    <OrigamIcon icon="mdi-check"   color="success" />
    <OrigamIcon icon="mdi-info"    color="info" />
    <OrigamIcon icon="mdi-warning" color="warning" />
</template>

For a one-off custom colour, use a :style binding instead of a raw hex:

vue
<OrigamIcon
    icon="mdi-heart"
    :style="{ '--origam-icon---color': '#e91e63' }"
/>

Polymorphic tag ​

vue
<template>
    <!-- Default — <i>, for EVERY notation -->
    <OrigamIcon icon="mdi-home" />
    <OrigamIcon icon="M12 2 L17 8 …" />

    <!-- Force a different tag -->
    <OrigamIcon icon="mdi-home" tag="span" />
</template>

⚠️ The root is <i> whatever the notation. <OrigamIcon> declares withDefaults(…, { tag: 'i' }) and forwards :tag="tag" to the leaf it dispatched to, so OrigamSvgIcon / OrigamComponentIcon / OrigamLigatureIcon's own tag: 'div' default is never reached through the dispatcher. Mounting a leaf directly does give you a <div>. Pinned by packages/tests/TU/components/Icon/icon-root-tag.spec.ts.

Click handler ​

When OrigamIcon receives an @click listener, aria-hidden is dropped (useIconAccessibility — see Accessibility) so assistive technology no longer ignores the icon. It does not become a button: since #653 no role="button" is added, and the icon still exposes no tabindex and no keyboard handler. Prefer <origam-btn icon="…"> (icon-only mode) for an actually clickable icon — see Migrating off @click on an icon (#653) below.

vue
<template>
    <OrigamIcon
        icon="mdi-close"
        aria-label="Close"
        @click="onClose"
    />
</template>

Slots ​

SlotDescription
defaultOverride the icon by passing its string name as the slot's text content. Useful for <OrigamIcon>$success</OrigamIcon>.

Props ​

Content ​

PropTypeDefaultDescription
iconTIconundefinedThe glyph. See the dispatch table at the top for every accepted form. Overridden by the default slot when that slot resolves to a text node
tagstring'i'Element the root renders as

Color ​

PropTypeDefaultDescription
colorTColorundefinedForeground. Falls back to --origam-icon---color, i.e. currentColor
bgColorTColorundefinedSurface behind the glyph. Both channels go through useBothColor

Sizing ​

PropTypeDefaultDescription
sizeTSize | numberundefinedOne of x-small · small · default · large · x-large. Emits origam-icon--size-{value}, whose rule reads --origam-icon---font-size-{xs|sm|md|lg|xl}. A number or an unrecognised length goes to sizeStyles as inline width / height instead — never both channels at once. Unset means no class and no rule: the glyph keeps the inherited font-size

Dimension (IDimensionProps) ​

Consumed by useDimension(props) — inline declarations on the root, so they outrank the size rung.

PropTypeDescription
width / heightnumber | stringExplicit box size
minWidth / minHeightnumber | string
maxWidth / maxHeightnumber | string

Shape, border and spacing ​

GroupPropsComposable
Shaperounded, roundedTopLeft / TopRight / BottomLeft / BottomRightuseRounded
Borderborder, borderBlock, borderInline, borderTop / Right / Bottom / Left, borderColor, borderStyle, the four per-side border*ColoruseBorder
Paddingpadding, paddingBlock, paddingInline, paddingTop / Right / Bottom / LeftusePadding
Marginmargin, marginBlock, marginInline, marginTop / Right / Bottom / LeftuseMargin
Commonsid, class, style—

Not a prop ​

disabled is deliberately absent. None of the five icon components ever read it, and an icon is a render element, not a control — there is nothing to disable. Paint the disabled state on whatever carries the icon (button, field, list item); the icon inherits its opacity and cursor. That also stops a single control from showing two divergent disabled treatments.

Emits ​

None. IIconComponentEmits is empty on purpose: none of the five components calls emit(…) anywhere. A @click listener you attach is a plain DOM listener — which is exactly what useIconAccessibility detects to drop aria-hidden (see Accessibility; it does not add role="button", since #653).

Props (interface) ​

ts
interface IIconComponentProps extends IIconProps,
    IColorProps, IBgColorProps, ICommonsComponentProps, ITagProps,
    ISizeProps, IPaddingProps, IMarginProps, IBorderProps,
    IDimensionProps, IRoundedProps {
}

interface IIconProps {
    icon?: TIcon
}

type TIcon =
    | string
    | Array<(string | [path: string, opacity: number])>
    | Component

Anatomy ​

Through <OrigamIcon> the root is always <i> (see Polymorphic tag), and the --size-* class only appears when size is set.

html
<!-- Class icon (mdi/fa) — <OrigamIcon icon="mdi-home" size="default" /> -->
<i class="origam-icon origam-icon--size-default mdi mdi-home"></i>

<!-- SVG icon — <OrigamIcon icon="M12 …" /> -->
<i class="origam-icon origam-icon--svg">
    <svg class="origam-icon__svg" viewBox="0 0 24 24" aria-hidden="true" focusable="false">
        <path d="…" />
    </svg>
</i>

<!-- Component icon — <OrigamIcon :icon="LucideHome" /> -->
<i class="origam-icon origam-icon--component">
    <!-- inner Vue component -->
</i>

Mounted directly rather than through the dispatcher, each leaf keeps its own tag: 'div' default:

html
<div class="origam-icon origam-icon--ligature">home</div>

Design tokens consumed ​

<OrigamIcon> reads its variables from packages/ds/src/assets/css/tokens/light.css and dark.css (SCSS twins under packages/ds/src/assets/scss/tokens/):

CSS variableDeclared value
--origam-icon---colorcurrentColor
--origam-icon---transition-durationvar(--origam-motion__duration---fast)
--origam-icon---transition-timing-functionvar(--origam-motion__easing---standard)
--origam-icon---font-size-xs … -4xlvar(--origam-font__size---{rung}), for xs sm md lg xl 2xl 3xl 4xl
--origam-icon---color-primaryvar(--origam-color__action--primary---bg)
--origam-icon---color-successvar(--origam-color__feedback--success---bg)
--origam-icon---color-warningvar(--origam-color__feedback--warning---bg)
--origam-icon---color-dangervar(--origam-color__feedback--danger---bg)
--origam-icon---color-infovar(--origam-color__feedback--info---bg)
--origam-icon---color-disabledvar(--origam-color__text---disabled)

Accessibility ​

  • aria-hidden="true" is applied automatically when no click handler is registered — purely-decorative icons stay invisible to screen readers.

⛔ Migrating off @click on an icon (#653) ​

If you attach @click directly to <origam-icon>, the rendered markup changed. Before #653, a click handler flipped the icon to role="button" + aria-hidden="false". role="button" is gone. The icon still receives the click (nothing stops a plain DOM listener) and aria-hidden still becomes "false", but assistive technology no longer announces it as a button — because it never behaved like one:

measured — <origam-icon icon="mdi-close" @click="…" aria-label="Close"/>
  before #653:  role="button"  aria-hidden="false"  aria-label="Close"
  today:        role=(none)    aria-hidden="false"  aria-label="Close"

role="button" was removed rather than fixed in place: the icon family sets no tabindex and no keyboard handler anywhere, so the role announced a control a keyboard or switch-device user could never reach (Tab never lands on it) or activate (Enter / Space do nothing) — a WCAG 2.1.1 (Keyboard) violation, not a defensible ARIA fallback. A dev-time console.warn still fires when the icon is clickable with no aria-label / aria-labelledby, and now points at the real fix instead:

vue
<!-- ❌ Before — announced role="button" with no keyboard access -->
<origam-icon icon="mdi-close" aria-label="Close" @click="onClose"/>

<!-- ✅ Now — origam-btn icon-only mode: a real <button>, full keyboard support for free -->
<origam-btn icon="mdi-close" :aria-label="t('btn_close', 'Close')" @click="onClose"/>

IBtnProps.icon accepts boolean | TIcon (icon-only mode); see OrigamBtn.md's Accessibility section — icon-only mode needs an aria-label you supply yourself, exactly like above, but on a real button.

Compared against the DS's own precedent for role="button" on a non-native element, OrigamCard (#392): Card pairs the role with tabindex="0" and a keydown handler, and does so only because its content model makes a native <button> illegal (Card renders flow content a <button> cannot legally contain). OrigamIcon has no such constraint — origam-btn is always available — so reproducing Card's pattern here would only duplicate OrigamBtn instead of removing the anti-pattern.

An earlier draft of this ticket also explored a typed clickable prop with a vue-tsc-enforced discriminated union. It was removed before release too: no component in the repo ever used it, and constraining an API nobody uses just papers over the real defect.

  • The inline <svg> leaf (OrigamSvgIcon) renders its glyph with aria-hidden="true" by default — no role — it never carries meaning on its own; the accessible name lives on the interactive ancestor, not the glyph. Since #660 it calls useIconAccessibility() like the other four leaves, so attaching a @click un-hides it and raises the same dev-time warning. Before that fix the attribute was hardcoded: a clickable OrigamSvgIcon stayed invisible to assistive technology for ever, and — unlike its siblings — warned about nothing.

Theming notes ​

  • currentColor makes every icon theme-aware out of the box: switching <html data-theme="dark"> re-resolves the cascading text colour and the icon follows. No Vue re-render required.
  • For an explicit theme-driven colour override, use the matching token directly: :style="{'--origam-icon---color': 'var(--origam-color__feedback--danger---fg)'}"
  • OrigamClassIcon — the mdi- / fa- font-class leaf.
  • OrigamSvgIcon — inline SVG path leaf.
  • OrigamComponentIcon — Vue-component wrapper leaf.
  • OrigamLigatureIcon — Material-style ligature leaf.
  • useIcon — composable that powers the dispatch.