React-Fallback-Img

Gestion intelligente des erreurs d'images pour vos applications React.

🌟 Présentation

React-Fallback-Img est une bibliothèque légère conçue pour améliorer l'expérience utilisateur (UX) en gérant élégamment les échecs de chargement d'images. Au lieu d'afficher l'icône de navigateur par défaut pour les liens brisés, cette lib permet de basculer sur une image de secours prédéfinie tout en gérant les états de chargement.

🚀 Installation

# Via npm
npm install react-fallback-img

# Via yarn
yarn add react-fallback-img

react et react-dom (>= 18) sont des peer dependencies : ils doivent déjà être présents dans votre projet.

🛠️ Utilisation Rapide

Remplacez simplement vos balises <img /> par SmartImage.

import { SmartImage } from 'react-fallback-img';
import 'react-fallback-img/dist/styles.css'; // styles de transition (optionnel)

const MyComponent = () => (
  <SmartImage
    src="https://api.monsite.com/photo.jpg"
    fallback="/assets/default-placeholder.png"
    alt="Description de l'image"
    className="img-responsive"
  />
);

⚙️ API & Propriétés (Props)

SmartImage accepte tous les attributs natifs d'une balise <img> (alt, width, loading, style, …) en plus des props suivantes :

| Propriété | Type | Défaut | Description | | -------------- | ---------- | -------- | ------------------------------------------------------ | | src | string | Requis | URL de l'image principale. | | fallback | string | Requis | URL de l'image si la source principale échoue. | | loader | ReactNode| null | Élément affiché pendant le chargement (ex : Skeleton). | | fadeDuration | number | 300 | Durée de l'animation d'apparition en millisecondes. | | onImageError | function | — | Fonction appelée si l'image principale ne charge pas. |

Exemple complet

<SmartImage
  src={user.avatarUrl}
  fallback="/assets/avatar-default.png"
  alt={user.name}
  fadeDuration={500}
  loader={<div className="skeleton" />}
  onImageError={(e) => console.warn('Avatar introuvable', e)}
/>

🧠 Fonctionnement Technique

La bibliothèque suit une logique d'état rigoureuse pour garantir la fluidité :

• Phase 1 : Tentative de chargement de src. L'état est à loading.
• Phase 2 (Succès) : L'image est affichée avec une transition d'opacité.
• Phase 2 (Erreur) : Si une erreur 404/500 survient, l'événement onError est intercepté. La source bascule sur fallback.
• Sécurité : Un drapeau interne empêche les boucles infinies si le fallback est lui-même introuvable.

Astuce : Vous pouvez cibler la classe CSS .rfi-image pour personnaliser les transitions globales de votre application. La durée du fondu est exposée via la variable CSS --rfi-fade-duration.

L'état courant est également exposé sur l'attribut data-rfi-status (loading | loaded | error) pour faciliter le ciblage CSS et les tests.

🧪 Développement

npm install      # installe les dépendances
npm run build    # compile vers dist/
npm test         # lance la suite de tests (Jest + Testing Library)

📄 Licence

Distribué sous licence MIT. Libre pour usage commercial et personnel.