Image

Bundled image

Import an image file from your project. The import is a file:// URL of the built copy, so wrap it in URL:

import { Image, Modifier } from "onescript/views"
import sunset from "./assets/sunset.png"

<Image
  url={new URL(sunset)}
  resizable
  modifier={Modifier
    .scaledToFill()
    .frame({ height: 160 })
    .clipped()}
/>

Bundled images work in apps and widgets. PNG, JPEG, GIF, and WebP are supported; SVG files are bundled but cannot be displayed by Image. Any local file:// URL can be shown, including files shared to an Action; a missing or undecodable file produces an explicit error. The same URL also works with fs, for example await fs.promises.readFile(new URL(sunset)).

Data URL

Declare the Data URL before passing it to Image:

import { Image, Modifier } from "onescript/views"

const logoDataURL = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII="

<Image
  dataURL={logoDataURL}
  resizable
  modifier={Modifier
    .scaledToFit()
    .padding({ horizontal: 12, vertical: 8 })}
/>

dataURL must use an image/* media type.

URL

Public HTTP(S) images use a standard Node-compatible URL object:

import { Image, Modifier } from "onescript/views"

const publicImageURL = new URL("https://example.com/public.png")

<Image
  url={publicImageURL}
  resizable
  modifier={Modifier
    .scaledToFit()
    .frame({ width: 120, height: 120 })}
/>

Request

Images that need Cookie, Authorization, or other headers use a standard Fetch API Request:

import { Image } from "onescript/views"

const privateImageRequest = new Request(
  "https://example.com/private.png",
  {
    method: "GET", // Defaults to GET when omitted
    headers: {
      Cookie: `session=${sessionId}`,
      Authorization: `Bearer ${token}`,
    },
  },
)

<Image
  request={privateImageRequest}
  resizable
/>

When an endpoint returns an image from a request body, pass another HTTP method:

const generatedImageRequest = new Request(
  "https://example.com/images/render",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      width: 800,
      height: 600,
    }),
  },
)

<Image request={generatedImageRequest} />

Exactly one of dataURL, url, or request is required. Image scaling uses the ordered scaledToFit and scaledToFill modifiers.

Network images show a system progress indicator while loading and localized error text after a failure. Failures are also written to the native log without request-header values.

OneScript passes the Request URL, method, headers, body, cache policy, and redirect policy. Request.credentials stays isolated from Cookie storage in the script's WKWebView and the app; pass a Cookie explicitly through Request.headers when authentication requires one. Same-origin redirects retain request headers, while cross-origin redirects remove Authorization, Cookie, and Proxy-Authorization.

In app views, iOS 17–26 uses OneScript's compatible loader and iOS 27 or later uses SwiftUI's native asynchronous image loader. Widget output downloads and validates the image before creating the timeline entry, so a failed request fails the widget execution with an explicit error.

Use Symbol for SF Symbols and Pikaicons. Invalid image data or sources produce an explicit error.