tailwindlabs/heroicons · error · Error

Importing from `@heroicons/vue` directly is not supported. P

Error message

Importing from `@heroicons/vue` directly is not supported. Please import from either `@heroicons/vue/16/solid`, `@heroicons/vue/20/solid`, `@heroicons/vue/24/solid`, or `@heroicons/vue/24/outline` instead.

What it means

The Vue package mirrors the React guard: importing from the root `@heroicons/vue` is unsupported in v2. The ESM root entry is a Proxy that throws on every property access except `__esModule`. Icons must come from `@heroicons/vue/16/solid`, `@heroicons/vue/20/solid`, `@heroicons/vue/24/solid`, or `@heroicons/vue/24/outline`.

Source

Thrown at vue/index.esm.js:11

// The only reason this file exists is to appease Vite's optimizeDeps feature which requires a root-level import.

export default new Proxy(
  {},
  {
    get: (_, property) => {
      if (property === '__esModule') {
        return {}
      }

      throw new Error(
        `Importing from \`@heroicons/vue\` directly is not supported. Please import from either \`@heroicons/vue/16/solid\`, \`@heroicons/vue/20/solid\`, \`@heroicons/vue/24/solid\`, or \`@heroicons/vue/24/outline\` instead.`
      )
    },
  }
)

View on GitHub (pinned to 616b7a4dbb)

Solutions

Change imports to a subpath: `import { BeakerIcon } from '@heroicons/vue/24/outline'`.
Update IDE auto-import settings so completions target the versioned subpaths.
Fix vite/webpack/tsconfig aliases or jest/vitest mappers that rewrite `@heroicons/vue/...` to the root entry.
Reinstall dependencies and clear the Vite dep-optimizer cache (`node_modules/.vite`) if stale resolution persists.

Example fix

// before
import { BeakerIcon } from '@heroicons/vue'

// after
import { BeakerIcon } from '@heroicons/vue/24/outline'

Defensive patterns

Strategy: validation

Validate before calling

// Vue app boot-time check
import * as vueIcons from '@heroicons/vue'
if (!vueIcons || !('BeakerIcon' in vueIcons)) {
  throw new Error("Do not import from '@heroicons/vue'; use '@heroicons/vue/24/outline' etc.")
}

Prevention

ESLint no-restricted-imports banning the '@heroicons/vue' root specifier.
Fix Vite aliases and clear node_modules/.vite cache after upgrades.
Point editor auto-imports at '@heroicons/vue/<size>/<style>'.
Codemod icon imports on every heroicons major bump.

When it happens

Trigger: `import { BeakerIcon } from '@heroicons/vue'` or any named import / property access on the Vue package root in an ESM/Vite context. The Proxy get trap throws immediately when the module property is read.

Common situations: Editor auto-imports resolving the bare `@heroicons/vue` specifier in Vue 3 + Vite projects; tutorials or snippets written before v2; upgrading a Vue app from heroicons v1 to v2 without updating import paths; path aliases collapsing subpath imports to the root.

Related errors

AI-assisted analysis of tailwindlabs/heroicons@616b7a4dbb (2026-08-31). Data as JSON: /api/errors/63fea2fefb67d16f. Report an issue: GitHub.