# Image

A versatile image component that extends the standard HTML img element with enhanced features including fallback support, different fit options, loading states, and aspect ratio control. This component provides a robust solution for displaying images with proper error handling and responsive behavior.

## Aliases

- Image
- Img
- Picture

## Props Breakdown

**Extends:** `ImgHTMLAttributes<HTMLImageElement>`

| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `src` | `string` | `undefined` | Yes | The URL of the image to display |
| `alt` | `string` | `undefined` | Yes | Alternative text for accessibility |
| `fallback` | `string` | `undefined` | No | The URL of the image to display if the image fails to load |
| `fit` | `'Fit' \| 'Fill' \| 'Crop'` | `'Fit'` | No | The fit option for the image |
| `onLoad` | `() => void` | `undefined` | No | Callback function when the image has loaded |
| `onError` | `(error: SyntheticEvent<HTMLImageElement>) => void` | `undefined` | No | Callback function when an error occurs while loading the image |
| `showLoading` | `boolean` | `false` | No | Flag to show a loading indicator for the image |
| `className` | `string` | `undefined` | No | Additional class for styling |
| `aspectRatio` | `string` | `natural aspect ratio` | No | The aspect ratio of the image |
| `width` | `string \| number` | `undefined` | No | Width of the image |
| `height` | `string \| number` | `undefined` | No | Height of the image |
| `loading` | `'eager' \| 'lazy'` | `undefined` | No | Loading behavior of the image |
| `decoding` | `'sync' \| 'async' \| 'auto'` | `undefined` | No | Decoding behavior of the image |

Plus all standard HTML img attributes (crossOrigin, referrerPolicy, sizes, srcSet, useMap, etc.).

## Examples

### Basic Image

```tsx
import { Image } from '@delightui/components';

function BasicImageExample() {
  return (
    <Image
      src="https://via.placeholder.com/300x200"
      alt="Placeholder image"
    />
  );
}
```

### Image with Fallback

```tsx
import { Image } from '@delightui/components';

function FallbackImageExample() {
  return (
    <Image
      src="https://invalid-url.com/image.jpg"
      alt="Failed image"
      fallback="https://via.placeholder.com/300x200?text=Fallback"
      onError={(error) => console.log('Image failed to load:', error)}
    />
  );
}
```

### Different Fit Options

```tsx
import { Image } from '@delightui/components';

function FitOptionsExample() {
  const imageUrl = "https://via.placeholder.com/400x300";

  return (
    <div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap' }}>
      <div>
        <h4>Fit (Default)</h4>
        <div style={{ width: '200px', height: '150px', border: '1px solid #ccc' }}>
          <Image
            src={imageUrl}
            alt="Fit example"
            fit="Fit"
          />
        </div>
      </div>

      <div>
        <h4>Fill</h4>
        <div style={{ width: '200px', height: '150px', border: '1px solid #ccc' }}>
          <Image
            src={imageUrl}
            alt="Fill example"
            fit="Fill"
          />
        </div>
      </div>

      <div>
        <h4>Crop</h4>
        <div style={{ width: '200px', height: '150px', border: '1px solid #ccc' }}>
          <Image
            src={imageUrl}
            alt="Crop example"
            fit="Crop"
          />
        </div>
      </div>
    </div>
  );
}
```

### Aspect Ratio Control

```tsx
import { Image } from '@delightui/components';

function AspectRatioExample() {
  const imageUrl = "https://via.placeholder.com/400x300";

  return (
    <div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap' }}>
      <div>
        <h4>16:9 Aspect Ratio</h4>
        <Image
          src={imageUrl}
          alt="16:9 aspect ratio"
          aspectRatio="16/9"
          style={{ width: '300px' }}
        />
      </div>

      <div>
        <h4>1:1 Aspect Ratio</h4>
        <Image
          src={imageUrl}
          alt="1:1 aspect ratio"
          aspectRatio="1/1"
          style={{ width: '200px' }}
        />
      </div>

      <div>
        <h4>4:3 Aspect Ratio</h4>
        <Image
          src={imageUrl}
          alt="4:3 aspect ratio"
          aspectRatio="4/3"
          style={{ width: '240px' }}
        />
      </div>
    </div>
  );
}
```

### Loading States

```tsx
import { Image, Spinner } from '@delightui/components';

function LoadingImageExample() {
  const [isLoading, setIsLoading] = useState(true);

  const handleLoad = () => {
    setIsLoading(false);
    console.log('Image loaded successfully');
  };

  const handleError = (error: any) => {
    setIsLoading(false);
    console.error('Image failed to load:', error);
  };

  return (
    <div style={{ position: 'relative', width: '300px', height: '200px' }}>
      {isLoading && (
        <div style={{
          position: 'absolute',
          top: 0,
          left: 0,
          right: 0,
          bottom: 0,
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          backgroundColor: '#f5f5f5'
        }}>
          <Spinner size="Medium" />
        </div>
      )}
      
      <Image
        src="https://via.placeholder.com/300x200"
        alt="Loading example"
        onLoad={handleLoad}
        onError={handleError}
        showLoading={true}
        style={{ opacity: isLoading ? 0 : 1, transition: 'opacity 0.3s' }}
      />
    </div>
  );
}
```

### Lazy Loading

```tsx
import { Image } from '@delightui/components';

function LazyLoadingExample() {
  const images = [
    { id: 1, url: 'https://via.placeholder.com/300x200/FF0000/FFFFFF?text=Image+1' },
    { id: 2, url: 'https://via.placeholder.com/300x200/00FF00/FFFFFF?text=Image+2' },
    { id: 3, url: 'https://via.placeholder.com/300x200/0000FF/FFFFFF?text=Image+3' },
    { id: 4, url: 'https://via.placeholder.com/300x200/FFFF00/000000?text=Image+4' },
    { id: 5, url: 'https://via.placeholder.com/300x200/FF00FF/FFFFFF?text=Image+5' }
  ];

  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '100vh' }}>
      {images.map((image) => (
        <div key={image.id}>
          <h3>Image {image.id}</h3>
          <Image
            src={image.url}
            alt={`Lazy loaded image ${image.id}`}
            loading="lazy"
            onLoad={() => console.log(`Image ${image.id} loaded`)}
          />
        </div>
      ))}
    </div>
  );
}
```

### Gallery Example

```tsx
import { Image } from '@delightui/components';

function GalleryExample() {
  const [selectedImage, setSelectedImage] = useState<string | null>(null);
  
  const images = [
    'https://via.placeholder.com/300x200/FF6B6B/FFFFFF?text=Photo+1',
    'https://via.placeholder.com/300x200/4ECDC4/FFFFFF?text=Photo+2',
    'https://via.placeholder.com/300x200/45B7D1/FFFFFF?text=Photo+3',
    'https://via.placeholder.com/300x200/96CEB4/FFFFFF?text=Photo+4',
    'https://via.placeholder.com/300x200/FFEAA7/000000?text=Photo+5',
    'https://via.placeholder.com/300x200/DDA0DD/FFFFFF?text=Photo+6'
  ];

  return (
    <div>
      <div style={{ 
        display: 'grid', 
        gridTemplateColumns: 'repeat(auto-fit, minmax(150px, 1fr))', 
        gap: '16px',
        marginBottom: '24px'
      }}>
        {images.map((src, index) => (
          <Image
            key={index}
            src={src}
            alt={`Gallery image ${index + 1}`}
            fit="Crop"
            aspectRatio="1/1"
            style={{ cursor: 'pointer' }}
            onClick={() => setSelectedImage(src)}
          />
        ))}
      </div>

      {selectedImage && (
        <div style={{
          position: 'fixed',
          top: 0,
          left: 0,
          right: 0,
          bottom: 0,
          backgroundColor: 'rgba(0, 0, 0, 0.8)',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          zIndex: 1000
        }} onClick={() => setSelectedImage(null)}>
          <Image
            src={selectedImage}
            alt="Selected image"
            style={{ maxWidth: '90%', maxHeight: '90%' }}
          />
        </div>
      )}
    </div>
  );
}
```

### Responsive Images

```tsx
import { Image } from '@delightui/components';

function ResponsiveImageExample() {
  return (
    <div style={{ maxWidth: '800px' }}>
      <h3>Responsive Image</h3>
      <Image
        src="https://via.placeholder.com/800x400"
        alt="Responsive image"
        style={{
          width: '100%',
          height: 'auto',
          maxWidth: '100%'
        }}
      />

      <h3>Fixed Aspect Ratio Responsive</h3>
      <Image
        src="https://via.placeholder.com/800x400"
        alt="Fixed aspect ratio responsive"
        aspectRatio="16/9"
        fit="Crop"
        style={{ width: '100%' }}
      />
    </div>
  );
}
```

### Error Handling

```tsx
import { Image, Text } from '@delightui/components';

function ErrorHandlingExample() {
  const [imageError, setImageError] = useState<string | null>(null);
  const [imageLoaded, setImageLoaded] = useState(false);

  const handleError = (error: any) => {
    setImageError('Failed to load image');
    console.error('Image error:', error);
  };

  const handleLoad = () => {
    setImageLoaded(true);
    setImageError(null);
  };

  return (
    <div>
      <Image
        src="https://invalid-image-url.com/nonexistent.jpg"
        alt="This will fail to load"
        fallback="https://via.placeholder.com/300x200/FF0000/FFFFFF?text=Error+Fallback"
        onError={handleError}
        onLoad={handleLoad}
      />
      
      {imageError && (
        <Text color="error" style={{ marginTop: '8px' }}>
          {imageError}
        </Text>
      )}
      
      {imageLoaded && (
        <Text color="success" style={{ marginTop: '8px' }}>
          Image loaded successfully!
        </Text>
      )}
    </div>
  );
}
```

### Image with Custom Styling

```tsx
import { Image } from '@delightui/components';

function CustomStyledImageExample() {
  return (
    <div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap' }}>
      <Image
        src="https://via.placeholder.com/200x200"
        alt="Rounded image"
        className="rounded-image"
        style={{ borderRadius: '50%' }}
      />

      <Image
        src="https://via.placeholder.com/200x200"
        alt="Border image"
        style={{ 
          border: '4px solid #007bff',
          borderRadius: '8px',
          boxShadow: '0 4px 8px rgba(0,0,0,0.1)'
        }}
      />

      <Image
        src="https://via.placeholder.com/200x200"
        alt="Grayscale image"
        style={{ 
          filter: 'grayscale(100%)',
          transition: 'filter 0.3s ease'
        }}
        onMouseEnter={(e) => {
          e.currentTarget.style.filter = 'grayscale(0%)';
        }}
        onMouseLeave={(e) => {
          e.currentTarget.style.filter = 'grayscale(100%)';
        }}
      />
    </div>
  );
}
```

### Performance Optimized

```tsx
import { Image } from '@delightui/components';

function PerformanceOptimizedExample() {
  return (
    <div>
      <h3>Optimized Image Loading</h3>
      <Image
        src="https://via.placeholder.com/800x600"
        alt="High resolution image"
        loading="lazy"
        decoding="async"
        width={400}
        height={300}
        style={{
          objectFit: 'cover',
          transition: 'transform 0.3s ease'
        }}
        onLoad={() => console.log('Image loaded and decoded')}
      />
    </div>
  );
}
```