# ImageWithFallback

A drop-in replacement for the native `<img>` element that gracefully handles broken or missing image URLs by displaying a placeholder SVG instead of a broken image icon.

---

## Import

```tsx
import { ImageWithFallback } from 'xertica-ui';
// or from the figma subpath (internal)
import { ImageWithFallback } from 'xertica-ui/ui';
```

---

## Basic Usage

```tsx
<ImageWithFallback
  src="https://example.com/photo.jpg"
  alt="User profile photo"
  className="w-32 h-32 rounded-lg object-cover"
/>
```

---

## Props

`ImageWithFallback` accepts all standard HTML `<img>` attributes:

| Prop        | Type                | Description                                                                |
| ----------- | ------------------- | -------------------------------------------------------------------------- |
| `src`       | `string`            | Image URL. If this fails to load, the fallback placeholder is shown.       |
| `alt`       | `string`            | Accessible alternative text (required for accessibility)                   |
| `className` | `string`            | CSS classes applied to both the `<img>` and the fallback container         |
| `style`     | `CSSProperties`     | Inline styles applied to both states                                       |
| `...rest`   | `ImgHTMLAttributes` | All other standard `<img>` attributes (`width`, `height`, `loading`, etc.) |

---

## Behavior

1. **Normal state**: Renders a standard `<img>` element with the provided `src`.
2. **Error state**: When the image fails to load (`onError` fires), the component switches to a fallback `<div>` containing a centered placeholder SVG (a simple broken-image icon).
3. **Fallback container**: The fallback `<div>` uses `bg-gray-100` and inherits the same `className` and `style` as the original image, so it maintains the same dimensions and shape.
4. **Original URL preserved**: The fallback `<img>` stores the original URL in `data-original-url` for debugging purposes.

---

## Usage Examples

### Hero Image with Fallback

```tsx
<ImageWithFallback
  src={article.heroImageUrl}
  alt={article.title}
  className="w-full h-48 object-cover rounded-t-lg"
/>
```

### User Avatar with Fallback

```tsx
<ImageWithFallback
  src={user.avatarUrl}
  alt={`${user.name} avatar`}
  className="w-10 h-10 rounded-full object-cover"
/>
```

> **Note**: For user avatars, prefer the `<Avatar>` component which has built-in fallback support via `<AvatarFallback>` (shows initials). Use `ImageWithFallback` for non-avatar images.

### Lazy Loading

```tsx
<ImageWithFallback
  src={product.imageUrl}
  alt={product.name}
  loading="lazy"
  className="w-full aspect-square object-contain"
/>
```

---

## Comparison: `ImageWithFallback` vs `Avatar`

| Feature       | `ImageWithFallback`                     | `Avatar`              |
| ------------- | --------------------------------------- | --------------------- |
| Fallback type | SVG placeholder icon                    | Text initials         |
| Use case      | General images, hero images, thumbnails | User profile pictures |
| Shape         | Any (controlled by `className`)         | Circle (default)      |
| Import        | `xertica-ui/ui`                         | `xertica-ui/ui`       |

---

## AI Rules

> [!IMPORTANT]
>
> - **Always provide `alt`**: The `alt` attribute is required for accessibility. Never omit it. Use an empty string (`alt=""`) only for purely decorative images.
> - **Use for external images**: Use `ImageWithFallback` whenever the image URL comes from an external source (API, user upload, CMS) that may be unavailable. For static local assets, a regular `<img>` is acceptable.
> - **Do not use for avatars**: For user profile pictures, use the `<Avatar>` + `<AvatarFallback>` pattern instead — it shows initials which is more informative than a broken-image icon.
> - **Maintain dimensions in fallback**: The fallback container inherits `className` and `style`, so always set explicit dimensions (via Tailwind classes like `w-32 h-32` or inline styles) to prevent layout shift when the fallback renders.