Best Practices with SolidJS

This guide collects practical recommendations for using Hugeicons in SolidJS 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/solid-js'
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 Vite or Rollup 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} class="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 with <Show>, use altIcon and showAlt on the same HugeiconsIcon:

import { createSignal } from 'solid-js'
import { HugeiconsIcon } from '@hugeicons/solid-js'
import { ViewIcon, ViewOffSlashIcon } from '@hugeicons-pro/core-stroke-rounded'
 
export function PasswordToggle() {
  const [visible, setVisible] = createSignal(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.

In Solid, don’t destructure props — that reads them once and breaks reactivity. Use mergeProps to apply defaults instead:

import { mergeProps } from 'solid-js'
import { HugeiconsIcon, type HugeiconsIconProps } from '@hugeicons/solid-js'
 
export function Icon(props: HugeiconsIconProps) {
  const merged = mergeProps({ size: 16, color: 'currentColor', strokeWidth: 1.5 }, props)
 
  return <HugeiconsIcon {...merged} />
}

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 class="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 signal.

Server-side rendering

@hugeicons/solid-js works with SolidStart and other Vite-based SSR setups out of the box. The package ships its source under the solid export condition, so vite-plugin-solid compiles it for both the server and the client and hydration matches without extra configuration.

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.