Integrations
Vue
Best Practices with Vue

Best Practices with Vue

This guide collects practical recommendations for using Hugeicons in Vue so your icons stay fast, consistent, and accessible.

Import icons efficiently

Always import only the icons you need from the specific package:

<script setup>
import { HugeiconsIcon } from '@hugeicons/vue'
import { Notification03Icon } from '@hugeicons/core-free-icons'
// or, for Pro:
// import { Notification03Icon } from '@hugeicons-pro/core-stroke-rounded'
</script>

Avoid wildcard imports (e.g. import * as Icons from '...') because they prevent bundlers from tree‑shaking unused icons and can increase your bundle size.

Keep icons accessible

Use different patterns for decorative vs meaningful icons:

  • Decorative icons (purely visual): keep them inside elements that already have accessible text.
  • Meaningful icons (e.g., trash, download): make sure there is a label.
<script setup>
import { HugeiconsIcon } from '@hugeicons/vue'
import { DownloadIcon, Delete01Icon } from '@hugeicons/core-free-icons'
</script>
 
<template>
  <!-- Icon with visible label (screen readers read the text) -->
  <button type="button">
    <HugeiconsIcon :icon="DownloadIcon" :size="18" class="mr-1" />
    Download
  </button>
 
  <!-- Icon-only button with aria-label -->
  <button type="button" aria-label="Delete">
    <HugeiconsIcon :icon="Delete01Icon" :size="18" />
  </button>
</template>

Avoid relying on icon shape alone to convey critical information; pair icons with text or tooltips where possible.

Use altIcon + showAlt for state

Instead of conditionally rendering two separate icons, use altIcon and showAlt on the same HugeiconsIcon:

<script setup>
import { ref } from 'vue'
import { HugeiconsIcon } from '@hugeicons/vue'
import { ViewIcon, ViewOffSlashIcon } from '@hugeicons-pro/core-stroke-rounded'
 
const visible = ref(false)
</script>
 
<template>
  <button
    type="button"
    @click="visible = !visible"
    :aria-label="visible ? 'Hide password' : 'Show password'"
  >
    <HugeiconsIcon
      :icon="ViewIcon"
      :altIcon="ViewOffSlashIcon"
      :showAlt="visible"
      :size="18"
    />
  </button>
</template>

This keeps your templates simpler and ensures both states share the same sizing and styling.

Create an app-level Icon wrapper

In many apps it’s helpful to create your own Icon component that forwards props to HugeiconsIcon while enforcing project-wide defaults for size, color, and stroke width.

<!-- components/Icon.vue -->
<script setup>
import { HugeiconsIcon } from '@hugeicons/vue'
 
const props = defineProps({
  icon: { type: Object, required: true },
  altIcon: { type: Object, default: null },
  showAlt: { type: Boolean, default: false },
  size: { type: Number, default: 16 },
  color: { type: String, default: 'currentColor' },
  strokeWidth: { type: Number, default: 1.5 },
})
</script>
 
<template>
  <HugeiconsIcon v-bind="props" v-bind="$attrs" />
</template>

Now you can use Icon throughout your project and adjust defaults (size, color, stroke width, theming) in one place without touching all call sites.

<script setup>
import Icon from '@/components/Icon.vue'
import { Delete01Icon } from '@hugeicons/core-free-icons'
</script>
 
<template>
  <button type="button" aria-label="Delete">
    <Icon :icon="Delete01Icon" :size="18" />
  </button>
</template>

Centralizing patterns like this keeps styling and accessibility consistent across your app.

Plan for dark mode and themes

When supporting dark mode, prefer currentColor and theme-aware classes instead of hard‑coding colors:

<script setup>
import { HugeiconsIcon } from '@hugeicons/vue'
import { Moon02Icon } from '@hugeicons/core-free-icons'
</script>
 
<template>
  <div class="text-slate-700 dark:text-slate-200">
    <HugeiconsIcon :icon="Moon02Icon" :size="20" color="currentColor" />
  </div>
</template>

If you need different styles per theme (e.g., duotone in dark mode), you can pair altIcon with your theme state.

Name and organize icons consistently

  • Use the shorter *Icon names (SearchIcon) for readability.
  • Use style-specific names (SearchStrokeRounded) only when you need multiple styles of the same icon in one file.
  • Group icons by domain in your codebase (e.g., icons/navigation.ts, icons/forms.ts) to make reuse easier.
// icons/navigation.ts
export { HomeIcon, SearchIcon, Notification03Icon, UserIcon } from '@hugeicons/core-free-icons'

Then import from your own modules instead of raw packages in components to keep imports tidy and consistent.

HugeiconsIcon WrapperExamples with Vue