Common Issues

Troubleshoot the most frequent configuration and performance issues when integrating Iconweuse in your codebase.

1. CORS and Font Loading Blocked

If you see errors in your developer console showing that webfont loading has been blocked by Cross-Origin Resource Sharing (CORS) policy, make sure to add the `crossorigin` attribute to your stylesheet reference:

<link href="https://cdn.iconweuse.com/icon/k4z9rm2tq1" rel="stylesheet" crossOrigin="anonymous" />

2. Next.js SSR Hydration Mismatch

When using dynamic icons inside server-rendered React applications (e.g. Next.js App Router), you may encounter hydration warnings if icons render differently on the server compared to the client.

To resolve this, ensure you are not generating random icons or referencing browser-specific elements (like `window.innerWidth`) during the initial render. If needed, wrap the component in a client-only fallback:

import { useEffect, useState } from 'react';
import { Search } from 'iconweuse/icons';

export function ClientOnlyIcon() {
  const [mounted, setMounted] = useState(false);
  useEffect(() => setMounted(true), []);

  if (!mounted) return <div class="w-6 h-6 bg-gray-200 animate-pulse rounded" />;
  return <Search />;
}

3. Icons render too large or break layout

If your webfont icons display excessively large upon page load, the browser might be rendering raw fallback text or symbols before our stylesheet has finished downloading.

• Always specify layout height and width explicitly using wrappers (e.g. <div class="h-6 w-6">).
• If using the webfont, utilize our pre-defined sizing classes like `iwu-lg`, `iwu-2x`, or customize them directly in CSS using font-size constraints.