Image

The Image component renders an image asset as the background of a div.

Use the dot-path form for assets in src/assets:

import Image from '@components/Media/Image/Image';

const App = () => <Image.icons.hud.grenade />;

With this approach, you don’t need to manually import the image, but you still benefit from path auto-completion and type checking while using the dot-path syntax. It is also the only format that can be packed into a texture atlas.

Installation

Available in Gameface UI projects only

Image depends on the generated types file and the images plugin in vite.config.mts, so it is only available in the full template.

To use it, start from the boilerplate.

Usage

By path

Every image under src/assets is exposed as a property of Image, matching the folder structure:

<Image.icons.hud.grenade />
<Image.icons.gamepad.xbox.a />

This is the recommended form for project assets and for any image that may be packed into an atlas.

By src

Use src for anything outside src/assets, for runtime paths, and for SVGs:

import Image from '@components/Media/Image/Image';
import MyImage from '@assets/my-image.png';

const App = () => <Image src={MyImage} style={{ width: '150px', height: '150px' }} />;

SVGs have no dot path

Dot paths are generated exclusively for raster images (.png, .jpg, .jpeg, .webp). SVGs are not atlas-compatible, so please import them directly and pass them through src:

import MySvg from '@assets/my-svg.svg';

<Image src={MySvg} />

API

Props

Prop Name	Type	Default	Description
style	JSX.CSSProperties	{}	Inline styles applied to the root element.
class	string	""	CSS class names.
ref	HTMLDivElement	undefined	DOM element reference.
src	string	undefined	Asset source. Not needed for dot-path images.
fill	boolean	false	Sets width and height to 100% of the parent.
options	{ repeat?, size?, position? }	undefined	Controls how the image is drawn.

options object properties

Prop Name	Accepted values	Default	Description
repeat	'both' | 'x' | 'y'	none	Repeat behavior.
size	'contain' | 'cover' or any valid background-size value	none	How the image is sized.
position	top, center, bottom, left, right, or any valid background-position value	none	Where the image sits.

Common patterns

Default size

Without options, Image defaults to a 3.5rem square and centers the image with contain. You can set your own size in the following way:

<Image.icons.hud.grenade style={{ width: '2rem', height: '2rem' }} />

Fill the container

fill sets the component to 100% x 100% of its parent:

<div style={{ width: '8rem', height: '8rem' }}>
    <Image.icons.hud.weapon fill />
</div>

Background mode

When you pass options, Image behaves like a background image. It drops the default size and fills only the dimensions you give it:

<Image
    src={Background}
    style={{ width: '150px', height: '150px' }}
    options={{ size: 'contain', position: 'center' }}
>
    <div>Content</div>
</Image>

Background mode disables atlassing

An image rendered with options is never packed into an atlas, because those CSS properties are exactly what the sprite needs.

Runtime lookup

A dot path can end in a computed key:

const key = () => currentGamepad();

<Dynamic component={Image.icons.gamepad.ps5[key()]} />

This pulls in the whole folder, because the build cannot know which key will run. If the project uses atlases, that can bloat the sheet. Keep these folders small or use an explicit map.

const glyphs = {
    a: Image.icons.gamepad.xbox.a,
    b: Image.icons.gamepad.xbox.b,
};

<Dynamic component={glyphs[key()]} />

Atlases

Images written as Image.folder.name can be packed into texture atlases at build time. This reduces texture count and texture binds, and it lets the project preload a handful of sheet PNGs before a view opens.

See Images and texture atlases for configuration and the build report.

Limitations

• Image can not be rendered inside a paragraph with cohinline enabled or InlineTextBlock; use a plain <img> there.
• Image is a div with a background, so it has no image error fallback.
• SVGs are not exposed on Image and cannot be packed into a raster atlas.
• Computed keys cost the whole folder.

Migrating from Icon and BackgroundImage

Both were deprecated in 5.0.0 and Image covers them.

Icon

Icon keys were relative to src/assets/icons; Image keys start at src/assets, so an icons. segment appears at the front. Icon rendered an <img> with a fallback image on load error. Image renders a div, so there is no error event and no fallback, but a mistyped path is now a build error instead.

<Icon.gamepad.xbox.a />
<Image.icons.gamepad.xbox.a />

BackgroundImage

The main behavior change is that Image has a 3.5rem default size unless you provide dimensions yourself.

<BackgroundImage src={bg} options={{ size: 'contain' }} />
<Image src={bg} options={{ size: 'contain' }} />