Best Practices with React

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

Import icons efficiently

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

import { HugeiconsIcon } from '@hugeicons/react'
import { Notification03Icon } from '@hugeicons/core-free-icons'
// or, for Pro:
// import { Notification03Icon } from '@hugeicons-pro/core-stroke-rounded'

Avoid wildcard imports (e.g. import * as Icons from ...) because they prevent bundlers like Webpack, Vite, or Next.js 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.

// Icon with visible label (screen readers read the text)
<button type="button">
  <HugeiconsIcon icon={DownloadIcon} size={18} className="mr-1" />
  Download
</button>
 
// Icon-only button with aria-label
<button type="button" aria-label="Delete">
  <HugeiconsIcon icon={Delete01Icon} size={18} />
</button>

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:

import { ViewIcon, ViewOffSlashIcon } from '@hugeicons-pro/core-stroke-rounded'
 
export function PasswordToggle() {
  const [visible, setVisible] = useState(false)
 
  return (
    <button type="button" onClick={() => setVisible(!visible)} aria-label={visible ? 'Hide password' : 'Show password'}>
      <HugeiconsIcon icon={ViewIcon} altIcon={ViewOffSlashIcon} showAlt={visible} size={18} />
    </button>
  )
}

This keeps your JSX 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.

import { HugeiconsIcon } from '@hugeicons/react'
import type { ComponentProps } from 'react'
 
type IconProps = ComponentProps<typeof HugeiconsIcon>
 
export function Icon({
  size = 16,
  color = 'currentColor',
  strokeWidth = 1.5,
  ...rest
}: IconProps) {
  return (
    <HugeiconsIcon
      size={size}
      color={color}
      strokeWidth={strokeWidth}
      {...rest}
    />
  )
}

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

<button type="button" aria-label="Delete">
  <Icon icon={Delete01Icon} size={18} />
</button>

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:

<div className="text-slate-700 dark:text-slate-200">
  <HugeiconsIcon icon={Moon02Icon} size={20} color="currentColor" />
</div>

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.