Best Practices

Preload Critical Icons

For icons visible immediately on page load:

<script src="https://cdn.icon.dev/id-project/sdk.min.js"></script>
<script>
  window.addEventListener('DOMContentLoaded', () => {
    IconSDK.preload(['logo', 'menu', 'close'])
  })
</script>

Preload icons that appear above the fold to eliminate loading flashes.

Use CSS for Consistent Sizing

Instead of data-icon-size on every element, define CSS classes:

.icon-sm { width: 16px; height: 16px; }
.icon-md { width: 24px; height: 24px; }
.icon-lg { width: 32px; height: 32px; }

<i data-icon="home" class="icon-md"></i>

Benefits:

Consistent sizing across your app
Easier to maintain and update
Better CSS cascade control

Add Loading States

Style icons during loading:

.icon-loading {
  opacity: 0.5;
  animation: pulse 1.5s ease-in-out infinite;
}

@keyframes pulse {
  0%, 100% { opacity: 0.5; }
  50% { opacity: 0.3; }
}

The SDK automatically adds .icon-loading while fetching and .icon-loaded when complete.

Conditional Preloading

Load icons based on context:

// User is authenticated
if (user.isAuthenticated) {
  IconSDK.preload(['settings', 'logout', 'profile'])
}

// Dark mode enabled
if (theme === 'dark') {
  IconSDK.preload(['moon', 'dark-mode-icons'])
}

// Mobile device
if (window.innerWidth < 768) {
  IconSDK.preload(['mobile-menu', 'hamburger'])
}

Batch Operations

When adding many icons at once, pause the observer:

// Pause observer
IconSDK.stopObserver()

// Add many icons
for (let i = 0; i < 100; i++) {
  const icon = document.createElement('i')
  icon.setAttribute('data-icon', 'item-' + i)
  container.appendChild(icon)
}

// Re-initialize and resume
IconSDK.init()
IconSDK.startObserver()

Only use this pattern for bulk operations. The observer is optimized for normal use.

Error Handling

Monitor failed icons:

// Check for errors
const failedIcons = document.querySelectorAll('[data-icon-error]')
failedIcons.forEach(icon => {
  const name = icon.getAttribute('data-icon')
  const error = icon.getAttribute('data-icon-error')
  console.error(`Icon "${name}" failed:`, error)

  // Replace with fallback
  icon.innerHTML = '❌'
})

Error types:

not-found — Icon doesn't exist in your project
load-failed — Network error or invalid SVG
invalid-svg — SVG content is malformed

Memory Management

For long-lived single-page applications:

// Clear cache periodically (e.g., every 30 minutes)
setInterval(() => {
  IconSDK.clearCache()
}, 30 * 60 * 1000)

// Or clear on route changes
router.afterEach(() => {
  if (IconSDK.cache.size > 100) {
    IconSDK.clearCache()
  }
})

Lazy Loading for Modals

Preload modal icons when opening:

function openModal() {
  // Preload modal-specific icons
  IconSDK.preload(['close', 'check', 'warning'])

  // Show modal
  modal.show()
}

Next Steps

Troubleshooting - Common issues and solutions
JavaScript API - Full API reference

Best Practices

On this page