Image Stable WINMACLNX

Renders an image from a local file path or a remote URL. Images are decoded on a background thread and cached in a 64-entry GPU image pool to prevent repeated uploads.

Import

import { Image } from '@glyx-dev/react'

Basic usage

// Local file (absolute path or app-relative)
<Image src="/assets/logo.png" width={80} height={80} />
 
// Remote URL — requires 'network' capability
<Image
  src="https://example.com/avatar.jpg"
  width={40}
  height={40}
  resizeMode="cover"
/>

Props

Prop	Type	Default	Description
`src`	`string`	—	File path or `https://` URL
`width`	`number`	`120`	Width in pixels
`height`	`number`	`120`	Height in pixels
`resizeMode`	`'cover' \| 'contain' \| 'stretch' \| 'center'`	`'stretch'`	How the image fills its box
`onError`	`(ev: { path: string }) => void`	—	Fired when the image fails to load
`style`	`ViewStyle`	—	Additional layout/style overrides

The src prop replaces the React Native source prop. Pass a plain string — either a local path or a remote URL.

Resize modes

Mode	Behaviour
`'cover'`	Scale to fill the box, cropping edges if needed — aspect ratio preserved
`'contain'`	Scale to fit inside the box — aspect ratio preserved, may letterbox
`'stretch'`	Scale to fill exactly — aspect ratio not preserved
`'center'`	Center at native size — no scaling

Examples

Avatar with rounded corners

<Image
  src={user.avatarUrl}
  width={48}
  height={48}
  resizeMode="cover"
  style={{ borderRadius: 24 }}
/>

Hero banner (contain)

<Image
  src="/assets/hero.png"
  width={600}
  height={240}
  resizeMode="contain"
  style={{ backgroundColor: '#000' }}
/>

Gallery grid

const photos = ['/p1.jpg', '/p2.jpg', '/p3.jpg']
 
<View style={{ flexDirection: 'row', gap: 8, flexWrap: 'wrap' }}>
  {photos.map((path, i) => (
    <Image
      key={i}
      src={path}
      width={120}
      height={120}
      resizeMode="cover"
      style={{ borderRadius: 8 }}
    />
  ))}
</View>

Dynamic image from camera capture

import { camera } from '@glyx-dev/react'
 
function CaptureDemo() {
  const [photoPath, setPhotoPath] = useState(null)
 
  const capture = async () => {
    const cam = await camera.open()
    const path = await cam.capture()
    setPhotoPath(path)
    await cam.close()
  }
 
  return (
    <View style={{ alignItems: 'center', gap: 16 }}>
      <Pressable onPress={capture} style={{ padding: 12, backgroundColor: '#4a9eff', borderRadius: 8 }}>
        <Text style={{ color: '#fff' }}>Capture</Text>
      </Pressable>
      {photoPath && (
        <Image src={photoPath} width={300} height={225} resizeMode="contain" />
      )}
    </View>
  )
}

Fallback on load error

When an image fails to load (missing file, unreadable format, broken path), Glyx renders a built-in broken-image placeholder — a gray panel with a red cross — sized to your width/height. The failure is also logged to the console with the path. Failed loads are not cached, so fixing the file and re-rendering the same src retries from disk.

To supply your own fallback artwork instead of the built-in placeholder, use onError:

function SafeImage({ src, width, height, fallbackSrc }) {
  const [resolved, setResolved] = useState(src)
 
  useEffect(() => setResolved(src), [src])
 
  return (
    <Image
      src={resolved}
      width={width}
      height={height}
      resizeMode="cover"
      onError={() => setResolved(fallbackSrc)}
    />
  )
}

Supported formats

PNG, JPEG, WebP, BMP, and SVG are decoded natively. SVG files are rasterized at the width/height you pass to <Image> (falling back to the SVG's intrinsic viewBox size when no size is given), so vector art stays crisp at any display size. Each distinct size is cached separately, like any bitmap.

⚠️

Remote images require the network capability in glyx.config.json:

{ "capabilities": { "network": { "allow": ["cdn.example.com"] } } }

Image cache

Images are stored in a GPU-side LRU cache keyed by src path (up to 64 entries). When the same src is rendered again it is served from GPU memory with no disk or decode overhead. Use distinct paths or append query strings to bust the cache for mutable files (e.g. user avatars that can be re-downloaded).

ScrollView Canvas (2D)