Scripting
Documentation
Changelog
Privacy
Documentation
Changelog
Privacy

Image

The Image component allows you to display images from various sources, such as system symbols, network URLs, local files, or UIImage objects. It supports dynamic image sources that change based on light or dark color schemes. Additionally, several view modifiers are available to customize the behavior and appearance of the Image component.

Type Definitions

ImageResizable

Defines how the image should be resized:

  • boolean:

    • true: Enables default resizing.
    • false: Disables resizing.

  • object:

    • capInsets (optional): EdgeInsets Defines insets for image stretching to control which parts of the image stretch and which remain fixed.

    • resizingMode (optional): ImageResizingMode Specifies the resizing mode, such as scaling or tiling.

ImageScale

Specifies relative image sizes available within the view:

  • 'large': Renders the image at a large size.
  • 'medium': Renders the image at a medium size.
  • 'small': Renders the image at a small size.

DynamicImageSource<T>

Defines a dynamic source that changes based on the system color scheme:

1type DynamicImageSource<T> = {
2  dark: T
3  light: T
4}

Used for adapting the image resource for light/dark modes. Supported in:

  • imageUrl (network images)
  • filePath (local file images)
  • image (UIImage objects)

Source Props

SystemImageProps

  • systemName (string, required) The name of a system-provided symbol. Refer to the SF Symbols library or use the SF Symbols Browser app to browse available symbol names.

  • variableValue (number, optional) A value between 0.0 and 1.0 for customizing the appearance of a variable symbol. (Has no effect for symbols that do not support variable values.)

  • resizable (ImageResizable, optional) Configures how the image is resized to fit its allocated space.

NetworkImageProps

  • imageUrl (string | DynamicImageSource<string>, required) The URL of the image to load. Supports dynamic sources via DynamicImageSource.

  • placeholder (VirtualNode, optional) A view displayed while the image is loading.

  • resizable (ImageResizable, optional) Configures how the image is resized to fit its allocated space.

FileImageProps

  • filePath (string | DynamicImageSource<string>, required) The path to the local image file. Supports dynamic sources via DynamicImageSource.

  • resizable (ImageResizable, optional) Configures how the image is resized to fit its allocated space.

UIImageProps

  • image (UIImage | DynamicImageSource<UIImage>, required) A UIImage object to display. Supports dynamic sources via DynamicImageSource.

  • resizable (ImageResizable, optional) Configures how the image is resized to fit its allocated space.

CommonViewProps

Modifiers applicable to the Image component and other views:

  • scaleToFit (boolean, optional) Scales the view to fit its parent container.

  • scaleToFill (boolean, optional) Scales the view to fill its parent container.

  • aspectRatio (object, optional) Configures the view's aspect ratio:

    • value (number or null, optional): The width-to-height ratio. If null, maintains the current aspect ratio.
    • contentMode (ContentMode, required): Determines whether the content fits or fills its parent.

  • imageScale (ImageScale, optional) Adjusts the size of images within the view. Options: 'large', 'medium', 'small'.

  • foregroundStyle (ShapeStyle or DynamicShapeStyle or object, optional) Configures the view's foreground elements:

    • primary: Style for the primary foreground elements.
    • secondary: Style for secondary elements.
    • tertiary (optional): Style for tertiary elements.

Rendering Behavior (ImageRenderingBehaviorProps)

Prop Type Default Description
resizable boolean | object false Controls whether the image resizes to fit its frame (see below)
renderingMode 'original' | 'template' 'original' Use "template" to allow tinting via foregroundColor
interpolation 'none' | 'low' | 'medium' | 'high' 'medium' Sets interpolation quality when scaling the image
antialiased boolean false Whether the image should use anti-aliasing
widgetAccentedRenderingMode WidgetAccentedRenderingMode (Widget-only) — Defines how the image renders in Widget accented mode

Usage Examples

  1. Dynamic Network Image Based on Color Scheme
1<Image
2  imageUrl={{
3    light: "https://example.com/image-light.png",
4    dark: "https://example.com/image-dark.png"
5  }}
6  placeholder={<Text>Loading...</Text>}
7/>
  1. Dynamic Local File Image
1<Image
2  filePath={{
3    light: Path.join(Script.directory, "light-mode.jpg"),
4    dark: Path.join(Script.directory, "dark-mode.jpg")
5  }}
6  resizable={true}
7/>
  1. Dynamic UIImage Object
1const lightImg = UIImage.fromFile('/path/to/light.png')
2const darkImg = UIImage.fromFile('/path/to/dark.png')
3
4<Image image={{ light: lightImg, dark: darkImg }} />
  1. System Symbol with Aspect Ratio and Scaling
1<Image
2  systemName="square.and.arrow.up.circle"
3  scaleToFit={true}
4  aspectRatio={{ value: 1.0, contentMode: "fit" }}
5  imageScale="medium"
6  foregroundStyle={{
7    primary: "blue",
8    secondary: "gray",
9  }}
10/>

Notes

  • Use DynamicImageSource to adapt images for light/dark mode with minimal logic.
  • Combine view modifiers like scaleToFit, scaleToFill, and aspectRatio to achieve precise layout configurations.
  • Use the foregroundStyle property for detailed styling of icons or symbols.
  • Ensure URLs and file paths provided for dynamic image sources are valid and accessible.
Outline