Image#

Displays images and textures. Maps to UI Toolkit's Image element.

import { Image } from "onejs-react"

Basic Usage#

Use the src prop with a path relative to your project's assets/ folder:

<Image src="logo.png" style={{ width: 100, height: 100 }} />

SVG files are also supported. They're parsed at runtime and rendered as resolution-independent vector graphics:

<Image src="icons/star.svg" style={{ width: 64, height: 64 }} />

src also accepts an absolute path or a full URL, which bypass asset resolution and load asynchronously:

<Image src="https://example.com/avatar.png" style={{ width: 64, height: 64 }} />

A bare relative name is the portable form and should be your default: an absolute path only exists on the machine that wrote it. See the Asset Loading guide for details on how paths are resolved.

Android & WebGL: in these builds, StreamingAssets lives inside the app package (or on a web server), so src loads asynchronously: the image appears as soon as it's loaded. No code changes needed.
If a URL in src never appears at all, update onejs-react to 0.1.44 or later: see Asset Loading.

Props#

Prop	Type	Default	Description
`src`	`string`		Path relative to `assets/` folder, an absolute path, or a URL (PNG, JPG, SVG)
`image`	`Texture2D`, `VectorImage`		Pre-loaded image object
`sprite`	`Sprite`		Sprite to display
`scaleMode`	`"StretchToFill"`, `"ScaleAndCrop"`, `"ScaleToFit"`	`"ScaleToFit"`	How the image scales
`tintColor`	`string`		Tint color applied to the image
`sourceRect`	`{ x, y, width, height }`		Region of the texture to show, in texture pixels from the top left. Not for sprites
`uv`	`{ x, y, width, height }`		Region of the texture to show, in 0 to 1 texture coordinates from the bottom left
`style`	`ViewStyle`		Inline styles
`className`	`string`		USS class name(s)

When both src and image are provided, src takes precedence. The image prop auto-detects whether you're passing a Texture2D or VectorImage and sets the appropriate property on the underlying UI Toolkit element.

SVG Support#

SVG files placed in your assets/ folder work with both src and loadImage():

import { loadImage } from "onejs-unity/assets"

// Via src prop (simplest)
<Image src="icons/heart.svg" style={{ width: 32, height: 32 }} />

// Via loadImage (when you need the object directly)
const heartIcon = loadImage("icons/heart.svg")
<Image image={heartIcon} style={{ width: 32, height: 32 }} />

Since SVGs are loaded as VectorImage objects, they scale cleanly at any size with no blurring or pixelation:

<View style={{ flexDirection: "row", alignItems: "flex-end" }}>
    <Image src="icon.svg" style={{ width: 16, height: 16 }} />
    <Image src="icon.svg" style={{ width: 48, height: 48 }} />
    <Image src="icon.svg" style={{ width: 128, height: 128 }} />
</View>

Under the hood, SVG files are parsed at runtime using Unity's built-in VectorGraphics module and rendered as GPU-accelerated vector images.

Scale Modes#

// Maintain aspect ratio, show entire image
<Image src="photo.png" scaleMode="ScaleToFit" />

// Maintain aspect ratio, fill container (crops edges)
<Image src="photo.png" scaleMode="ScaleAndCrop" />

// Ignore aspect ratio, fill container
<Image src="photo.png" scaleMode="StretchToFill" />

Pre-loaded Images#

For images loaded from custom paths or computed sources, use the image prop:

import { loadImage } from "onejs-unity/assets"

const avatar = loadImage(`avatars/${userId}.png`)
<Image image={avatar} style={{ width: 64, height: 64, borderRadius: 32 }} />

Background Images#

Any element can use an image as its background via the style prop:

import { loadImage } from "onejs-unity/assets"

const bg = loadImage("card-bg.png")

<View style={{ backgroundImage: bg, width: 300, height: 200, padding: 20 }}>
    <Label text="Card Content" style={{ color: "#fff" }} />
</View>

Cache Management#

The Image component caches loaded images for the lifetime of the JS context. To force a reload (e.g., after replacing files on disk):

import { clearImageCache } from "onejs-react"

clearImageCache()

GPU Compute Textures#

RenderTextures from GPU compute can be displayed as background images:

import { compute } from "onejs-unity"

function ComputeVisualization() {
    const [rt, setRt] = useState(null)

    useEffect(() => {
        const renderTex = compute.renderTexture({ width: 256, height: 256 })
        setRt(renderTex)
        return () => renderTex.dispose()
    }, [])

    return (
        <View style={{ backgroundImage: rt, width: 256, height: 256 }} />
    )
}