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

npm install @xsolla/xui-image-thumbnail
# or
yarn add @xsolla/xui-image-thumbnail

Demo

Basic ImageThumbnail

import * as React from 'react';
import { ImageThumbnail } from '@xsolla/xui-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

import * as React from 'react';
import { ImageThumbnail } from '@xsolla/xui-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

import * as React from 'react';
import { ImageThumbnail } from '@xsolla/xui-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

import * as React from 'react';
import { ImageThumbnail } from '@xsolla/xui-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

import * as React from 'react';
import { ImageThumbnail } from '@xsolla/xui-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

import * as React from 'react';
import { ImageThumbnail } from '@xsolla/xui-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:

import { ImageThumbnail } from '@xsolla/xui-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 | | :--- | :--- | :------ | :---------- | | 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. | | className | string | - | Custom className for the container. |

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 |

Theming

ImageThumbnail uses minimal theming, primarily relying on the passed props:

// Overlay styles
overlay="fade"  // linear-gradient(to top, rgba(0,0,0,0.48), transparent)
overlay="dark"  // rgba(0,0,0,0.48)

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