OptimizedImage

OptimizedImage is a layout and retry wrapper around expo-image. It reads the native 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 ExampleCopy Anchor Link

import { OvokProvider } from "@ovok/core/next/react";
import { Ovok } from "@ovok/native/next";
import { OptimizedImage } from "@ovok/native/image";
import * as SecureStore from "expo-secure-store";
import * as React from "react";

const client = new Ovok({
  baseUrl: "https://api.example.com",
  tenantCode: "example",
  secureStore: SecureStore,
});

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

export default BasicImage;

PropsCopy Anchor Link

Every prop, with its type and description, is listed in the @ovok/native/image API reference.

Key FeaturesCopy Anchor Link

• 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 SystemCopy Anchor Link

• 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 BenefitsCopy Anchor Link

Memory ManagementCopy Anchor Link

• 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 EfficiencyCopy Anchor Link

• Client URL optimization: Width, height, and fit query parameters are added only when the URI matches the native client 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.

DependenciesCopy Anchor Link

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

Performance ConsiderationsCopy Anchor Link

Optimization StrategyCopy Anchor Link

• 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 handlingCopy Anchor Link

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 UsageCopy Anchor Link

• 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