# Image

A cross-platform React image component with built-in aspect ratio presets and support for overlay content. Maintains consistent dimensions across different image sizes.

## Installation

```bash
npm install @xsolla/xui-image
```

## Demo

### Basic Image

```tsx
import * as React from "react";
import { Image } from "@xsolla/xui-image";

export default function BasicImage() {
  return <Image src="https://example.com/photo.jpg" alt="Sample photo" />;
}
```

### With Aspect Ratio

```tsx
import * as React from "react";
import { Image } from "@xsolla/xui-image";

export default function RatioImage() {
  return (
    <Image
      src="https://example.com/photo.jpg"
      alt="16:9 photo"
      ratio="16:9"
      width={400}
    />
  );
}
```

### With Border Radius

```tsx
import * as React from "react";
import { Image } from "@xsolla/xui-image";

export default function RoundedImage() {
  return (
    <Image
      src="https://example.com/photo.jpg"
      alt="Rounded photo"
      ratio="1:1"
      width={200}
      borderRadius={16}
    />
  );
}
```

### With Overlay Slot

```tsx
import * as React from "react";
import { Image } from "@xsolla/xui-image";

export default function OverlayImage() {
  return (
    <Image
      src="https://example.com/photo.jpg"
      alt="Photo with overlay"
      ratio="16:9"
      width={400}
      slot={
        <div
          style={{
            background: "rgba(0,0,0,0.5)",
            color: "white",
            padding: 16,
            width: "100%",
            height: "100%",
            display: "flex",
            alignItems: "center",
            justifyContent: "center",
          }}
        >
          Overlay Content
        </div>
      }
    />
  );
}
```

## Anatomy

```jsx
import { Image } from "@xsolla/xui-image";

<Image
  src="image-url.jpg" // Image source URL
  alt="Description" // Alt text for accessibility
  ratio="1:1" // Aspect ratio preset
  customRatio="21 / 9" // Custom ratio (when ratio="Custom")
  width={200} // Container width
  borderRadius={0} // Border radius
  slot={<Overlay />} // Overlay content
  style={{}} // Container styles
  imageStyle={{}} // Image element styles
/>;
```

## Examples

### Aspect Ratio Gallery

```tsx
import * as React from "react";
import { Image } from "@xsolla/xui-image";

export default function RatioGallery() {
  const src = "https://example.com/photo.jpg";

  return (
    <div style={{ display: "flex", gap: 16, flexWrap: "wrap" }}>
      <div>
        <p>1:1 (Square)</p>
        <Image src={src} ratio="1:1" width={150} />
      </div>
      <div>
        <p>16:9 (Widescreen)</p>
        <Image src={src} ratio="16:9" width={200} />
      </div>
      <div>
        <p>4:3 (Standard)</p>
        <Image src={src} ratio="4:3" width={180} />
      </div>
      <div>
        <p>3:2 (Photo)</p>
        <Image src={src} ratio="3:2" width={180} />
      </div>
      <div>
        <p>2:3 (Portrait)</p>
        <Image src={src} ratio="2:3" width={120} />
      </div>
      <div>
        <p>9:16 (Story)</p>
        <Image src={src} ratio="9:16" width={100} />
      </div>
    </div>
  );
}
```

### Custom Aspect Ratio

```tsx
import * as React from "react";
import { Image } from "@xsolla/xui-image";

export default function CustomRatioImage() {
  return (
    <Image
      src="https://example.com/ultrawide.jpg"
      alt="Ultra-wide photo"
      ratio="Custom"
      customRatio="21 / 9"
      width={400}
    />
  );
}
```

### Placeholder State

```tsx
import * as React from "react";
import { Image } from "@xsolla/xui-image";

export default function PlaceholderImage() {
  return (
    <Image
      ratio="16:9"
      width={400}
      slot={<span style={{ color: "#999" }}>Loading...</span>}
    />
  );
}
```

## API Reference

### Image

**Image Props:**

| Prop         | Type               | Default  | Description                                                                                                   |
| :----------- | :----------------- | :------- | :------------------------------------------------------------------------------------------------------------ |
| `testID`     | `string`           | —        | Test ID for testing frameworks. On web this renders as `data-testid`; on React Native it renders as `testID`. |
| src          | `string`           | -        | Image source URL.                                                                                             |
| alt          | `string`           | `""`     | Alt text for accessibility.                                                                                   |
| ratio        | `ImageRatio`       | `"1:1"`  | Aspect ratio preset.                                                                                          |
| customRatio  | `string \| number` | -        | Custom ratio when ratio is "Custom".                                                                          |
| width        | `number \| string` | `"100%"` | Container width.                                                                                              |
| borderRadius | `number \| string` | `0`      | Border radius of container.                                                                                   |
| slot         | `ReactNode`        | -        | Overlay content (centered).                                                                                   |
| style        | `CSSProperties`    | -        | Container styles.                                                                                             |
| imageStyle   | `CSSProperties`    | -        | Image element styles.                                                                                         |

**ImageRatio Type:**

```typescript
type ImageRatio =
  | "1:1" // Square
  | "2:3" // Portrait
  | "3:2" // Landscape photo
  | "16:9" // Widescreen
  | "4:3" // Standard
  | "9:16" // Story/mobile
  | "Custom"; // Use customRatio
```

## Behavior

- Image fills container with `object-fit: cover`
- Background color shows when image hasn't loaded
- Slot content overlays the image (centered)
- Maintains aspect ratio regardless of source image dimensions

## Accessibility

- Always provide meaningful `alt` text
- Decorative images can use `alt=""`
- Slot content should be accessible if interactive