# OptimizedImage

Canonical page: https://docs.ovok.com/native-sdk/guide/components/optimized-image

`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 Example [#basic-example]

```tsx
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;
```

## Props [#props]

Every prop, with its type and description, is listed in the [`@ovok/native/image` API reference](/native-sdk/reference/image).

## Key Features [#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 [#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 [#performance-benefits]

### Memory Management [#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 [#network-efficiency]

- **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.

## Dependencies [#dependencies]

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

## Performance Considerations [#performance-considerations]

### Optimization Strategy [#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 [#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.

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

### Memory Usage [#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`