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

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

Demo

Basic Image

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

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

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

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

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

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

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

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 | | :--- | :--- | :------ | :---------- | | 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:

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