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 'veloxkit'

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
`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 'veloxkit'
 
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

VeloxKit does not fire onError today — handle missing files by checking the path exists with fs.exists() before rendering, or show a placeholder by default:

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

Supported formats

PNG, JPEG, WebP, and BMP are decoded natively. SVG support is planned for v0.4.

⚠️

Remote images require the network capability in veloxkit.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)