OptimizedImage

OptimizedImage is a layout and retry wrapper around expo-image. It reads the client base URL from OvokProvider, so render it below that provider.

A layout and retry wrapper for React Native applications. It calculates dimensions, adds sizing parameters to matching client URLs, and delegates loading and caching to expo-image.

Basic Example

import { OvokClient, OvokProvider } from "@ovok/core";
import { ExpoClientStorage } from "@ovok/native";
import { OptimizedImage } from "@ovok/native/image";
import * as React from "react";

const client = new OvokClient({
  baseUrl: "https://api.example.com",
  storage: new ExpoClientStorage(),
});

const BasicImage = () => (
  <OvokProvider client={client}>
    <OptimizedImage
      uri="https://placehold.co/600x400/000/fff?text=Image"
      width={"100%"}
    />
  </OvokProvider>
);

export default BasicImage;

Props

Prop	Type	Default	Description
uri	string	—	Image URI. Required.
width	number | percentage string | "auto"	—	Calculated image width.
height	number | percentage string | "auto"	—	Calculated image height.
fit	"cover" | "contain" | "fill" | "inside" | "outside"	"contain"	expo-image content fit.
aspectRatio	number	measured or 1	Aspect ratio used for calculated dimensions.
containerStyle	StyleProp<ViewStyle>	—	Style for the outer layout container.
fallback	ImageProps["source"]	placeholder or none	Source shown after retries are exhausted.
maxRetries	number	3	Retry attempts before the fallback is shown.
placeholder	ImageProps["source"]	—	Placeholder while loading and fallback when no fallback is supplied.
style	ImageProps["style"] without width/height/aspectRatio/contentFit	—	Style for the rendered image.

All other expo-image props are forwarded except source and style. The component requires uri; it does not accept an expo-image source object.

Key Features

• Client URL parameters: Adds calculated width, height, and fit parameters only to matching client URLs
• Flexible Dimensions: Support for fixed, percentage, and auto-calculated dimensions
• Aspect Ratio Management: Automatic aspect ratio calculation and preservation
• Native image loading: Delegates loading and cache behavior to expo-image
• Responsive sizing: Container-aware sizing with layout-based calculations
• Host-controlled content: The wrapper does not assume a medical image source or upload workflow

Responsive Design System

• Container Awareness: Images can use parent container dimensions when width or height is calculated
• Percentage Support: Flexible sizing with percentage-based dimensions
• Auto Calculation: Intelligent fallback to calculated dimensions
• Aspect Ratio Preservation: Maintains image proportions across different sizes

Performance Benefits

Memory Management

• expo-image Integration: Native-level memory management
• Placeholder support: Passes placeholders through to expo-image
• Retry fallback: Replaces the rendered source after the bounded retry policy is exhausted

Network Efficiency

• Client URL optimization: Width, height, and fit query parameters are added only when the URI matches the OvokClient base URL. External URLs are returned unchanged.
• No network guarantee: expo-image owns the actual request and cache behavior; this wrapper does not promise request deduplication, progressive loading, or CDN use.

Dependencies

• expo-image - High-performance image component with native optimization

Performance Considerations

Optimization Strategy

• Placeholder Support: The placeholder is passed to expo-image.
• Bounded Retry: useImage retries up to maxRetries before the rendered source is changed to fallback, or to placeholder when no fallback is supplied.
• Error Handling: onError is forwarded to the rendered expo-image instance. It is not a callback for the retry hook's final outcome.

Failure handling

OptimizedImage retries failed preloads three times by default through expo-image. Set maxRetries to change the limit and pass fallback to render a local or remote image after the retries are exhausted. The visible expo-image still owns its own load lifecycle, so onLoad/onError describe that rendered instance rather than the internal preload. When the fallback uses different intrinsic dimensions, the wrapper keeps the calculated container dimensions and can stretch or distort the fallback; provide matching aspect ratio/size assets or an explicit layout when preserving its shape matters. Because the wrapper preloads through useImage and then renders an expo-image, request deduplication depends on expo-image's native cache; do not build billing, retry, or analytics logic on an assumption that exactly one network request occurs.

<OptimizedImage
  uri={avatarUrl}
  placeholder={require("./avatar-placeholder.png")}
  fallback={require("./avatar-fallback.png")}
  maxRetries={2}
  onError={handleImageError}
/>

Memory Usage

• Efficient Scaling: Optimal memory usage for different image sizes
• Cache Management: Intelligent cache eviction policies
• Resource ownership: Native loading, caching, and cleanup remain owned by expo-image