# ImageThumbnail

A cross-platform React component for displaying image thumbnails with overlays, tags at all four corners, and center content (like play buttons). Perfect for video thumbnails, screenshot galleries, and media previews.

## Installation

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

## Demo

### Basic ImageThumbnail

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

export default function BasicThumbnail() {
  return (
    <ImageThumbnail
      src="https://example.com/screenshot.jpg"
      alt="Game screenshot"
      ratio="16:9"
      width={320}
    />
  );
}
```

### Video Thumbnail with Play Button

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

const PlayButton = () => (
  <div
    style={{
      width: 48,
      height: 48,
      borderRadius: 24,
      backgroundColor: "rgba(0, 0, 0, 0.5)",
      display: "flex",
      alignItems: "center",
      justifyContent: "center",
    }}
  >
    <svg width="24" height="24" viewBox="0 0 24 24" fill="white">
      <path d="M8 5v14l11-7z" />
    </svg>
  </div>
);

export default function VideoThumbnail() {
  return (
    <ImageThumbnail
      src="https://example.com/video-preview.jpg"
      alt="Video preview"
      ratio="16:9"
      width={320}
      overlay="fade"
      centerContent={<PlayButton />}
    />
  );
}
```

### Thumbnail with Tags

```tsx
import * as React from "react";
import { ImageThumbnail } from "@xsolla/xui-b2c-image-thumbnail";
import { Tag } from "@xsolla/xui-tag";
import { XsollaTicket } from "@xsolla/xui-icons-currency";

export default function ThumbnailWithTags() {
  return (
    <ImageThumbnail
      src="https://example.com/screenshot.jpg"
      alt="Screenshot with reward"
      ratio="16:9"
      width={320}
      overlay="fade"
      tagsBottomLeft={
        <Tag size="sm" tone="secondary" icon={<XsollaTicket />}>
          5x
        </Tag>
      }
    />
  );
}
```

### All Corner Tags

```tsx
import * as React from "react";
import { ImageThumbnail } from "@xsolla/xui-b2c-image-thumbnail";
import { Tag } from "@xsolla/xui-tag";
import { Badge } from "@xsolla/xui-badge";

export default function AllCornerTags() {
  return (
    <ImageThumbnail
      src="https://example.com/screenshot.jpg"
      alt="Screenshot with all tags"
      ratio="16:9"
      width={400}
      overlay="fade"
      tagsTopLeft={
        <Tag size="sm" tone="brand">
          NEW
        </Tag>
      }
      tagsTopRight={
        <Tag size="sm" tone="secondary">
          2:30
        </Tag>
      }
      tagsBottomLeft={
        <Tag size="sm" tone="secondary">
          5x Tickets
        </Tag>
      }
      tagsBottomRight={
        <Badge size="lg" tone="success">
          HD
        </Badge>
      }
    />
  );
}
```

### Overlay Types

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

export default function OverlayTypes() {
  return (
    <div style={{ display: "flex", gap: 16 }}>
      <div>
        <p>No Overlay</p>
        <ImageThumbnail
          src="https://example.com/image.jpg"
          ratio="16:9"
          width={200}
          overlay="none"
        />
      </div>
      <div>
        <p>Fade Overlay</p>
        <ImageThumbnail
          src="https://example.com/image.jpg"
          ratio="16:9"
          width={200}
          overlay="fade"
        />
      </div>
      <div>
        <p>Dark Overlay</p>
        <ImageThumbnail
          src="https://example.com/image.jpg"
          ratio="16:9"
          width={200}
          overlay="dark"
        />
      </div>
    </div>
  );
}
```

### Aspect Ratios

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

export default function AspectRatios() {
  const ratios = ["1:1", "16:9", "4:3", "3:2", "9:16"] as const;

  return (
    <div style={{ display: "flex", gap: 16, flexWrap: "wrap" }}>
      {ratios.map((ratio) => (
        <div key={ratio}>
          <p>{ratio}</p>
          <ImageThumbnail
            src="https://example.com/image.jpg"
            ratio={ratio}
            width={150}
            overlay="fade"
          />
        </div>
      ))}
    </div>
  );
}
```

## Anatomy

Import the component and use it directly:

```jsx
import { ImageThumbnail } from "@xsolla/xui-b2c-image-thumbnail";

<ImageThumbnail
  src="..." // Required: Image URL
  alt="Description" // Alt text
  ratio="16:9" // Aspect ratio
  width={320} // Width
  overlay="fade" // Overlay type
  centerContent={<PlayBtn />} // Center content
  tagsTopLeft={<Tag />} // Top-left tags
  tagsTopRight={<Tag />} // Top-right tags
  tagsBottomLeft={<Tag />} // Bottom-left tags
  tagsBottomRight={<Tag />} // Bottom-right tags
  onPress={() => {}} // Click handler
/>;
```

## API Reference

### ImageThumbnail

A media thumbnail component with tag support.

**ImageThumbnail 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`                                                           | required | Image source URL.                                                                                             |
| alt             | `string`                                                           | `""`     | Alt text for the image.                                                                                       |
| ratio           | `"1:1" \| "16:9" \| "4:3" \| "3:2" \| "2:3" \| "9:16" \| "custom"` | `"16:9"` | Aspect ratio.                                                                                                 |
| customRatio     | `number`                                                           | -        | Custom aspect ratio (when ratio is 'custom').                                                                 |
| width           | `number \| string`                                                 | `"100%"` | Width of the thumbnail.                                                                                       |
| height          | `number \| string`                                                 | -        | Fixed height (overrides ratio).                                                                               |
| borderRadius    | `number`                                                           | `4`      | Border radius in pixels.                                                                                      |
| overlay         | `"none" \| "fade" \| "dark"`                                       | `"fade"` | Overlay type.                                                                                                 |
| centerContent   | `ReactNode`                                                        | -        | Content in the center (e.g., play button).                                                                    |
| tagsTopLeft     | `ReactNode`                                                        | -        | Tags in top-left corner.                                                                                      |
| tagsTopRight    | `ReactNode`                                                        | -        | Tags in top-right corner.                                                                                     |
| tagsBottomLeft  | `ReactNode`                                                        | -        | Tags in bottom-left corner.                                                                                   |
| tagsBottomRight | `ReactNode`                                                        | -        | Tags in bottom-right corner.                                                                                  |
| onPress         | `() => void`                                                       | -        | Click handler.                                                                                                |
| tagPadding      | `number`                                                           | `8`      | Padding for tag positions.                                                                                    |
| tagGap          | `number`                                                           | `4`      | Gap between stacked tags.                                                                                     |

**Overlay Types:**

| Type | Description                                  |
| :--- | :------------------------------------------- |
| none | No overlay                                   |
| fade | Gradient fade from bottom (semi-transparent) |
| dark | Solid dark overlay                           |

**Aspect Ratio Values:**

| Ratio | Numeric Value | Common Use        |
| :---- | :------------ | :---------------- |
| 1:1   | 1             | Square thumbnails |
| 16:9  | 1.78          | Video, widescreen |
| 4:3   | 1.33          | Standard photos   |
| 3:2   | 1.5           | DSLR photos       |
| 2:3   | 0.67          | Portrait          |
| 9:16  | 0.56          | Vertical video    |

## Accessibility

- Uses semantic `img` element with alt text
- Interactive when `onPress` is provided
- Tags and center content can include accessible labels
- Supports keyboard navigation when interactive