A view that displays an image.
Use an `Image` instance when you want to add images to your SwiftUI app.
You can create images from many sources:
* Image files in your app's asset library or bundle. Supported types include
PNG, JPEG, HEIC, and more.
* Instances of platform-specific image types, like
<doc://com.apple.documentation/documentation/UIKit/UIImage> and
<doc://com.apple.documentation/documentation/AppKit/NSImage>.
* A bitmap stored in a Core Graphics
<doc://com.apple.documentation/documentation/coregraphics/cgimage>
instance.
* System graphics from the SF Symbols set.
The following example shows how to load an image from the app's asset
library or bundle and scale it to fit within its container:
Image("Landscape_4")
.resizable()
.aspectRatio(contentMode: .fit)
Text("Water wheel")
You can use methods on the `Image` type as well as
standard view modifiers to adjust the size of the image to fit your app's
interface. Here, the `Image` type's
``Image/resizable(capInsets:resizingMode:)`` method scales the image to fit
the current view. Then, the
``View/aspectRatio(_:contentMode:)`` view modifier adjusts
this resizing behavior to maintain the image's original aspect ratio, rather
than scaling the x- and y-axes independently to fill all four sides of the
view. The article
<doc:Fitting-Images-into-Available-Space> shows how to apply scaling,
clipping, and tiling to `Image` instances of different sizes.
An `Image` is a late-binding token; the system resolves its actual value
only when it's about to use the image in an environment.
### Making images accessible
To use an image as a control, use one of the initializers that takes a
`label` parameter. This allows the system's accessibility frameworks to use
the label as the name of the control for users who use features like
VoiceOver. For images that are only present for aesthetic reasons, use an
initializer with the `decorative` parameter; the accessibility systems
ignore these images.
Creates an unlabeled, decorative image, with a variable value.
This initializer creates an image using a using a symbol in the
specified bundle. The rendered symbol may alter its appearance to
represent the value provided in `variableValue`.
> Note: See WWDC22 session [10158: Adopt variable color in SF
Symbols](https://developer.apple.com/wwdc22/10158/) for details on
how to create symbols that support variable values.
SwiftUI ignores this image for accessibility purposes.
- Parameters:
- name: The name of the image resource to lookup.
- variableValue: An optional value between `0.0` and `1.0` that
the rendered image can use to customize its appearance, if
specified. If the symbol doesn't support variable values, this
parameter has no effect.
- bundle: The bundle to search for the image resource. If
`nil`, SwiftUI uses the main `Bundle`. Defaults to `nil`.
Creates an unlabeled, decorative image based on a Core Graphics image
instance.
SwiftUI ignores this image for accessibility purposes.
- Parameters:
- cgImage: The base graphical image.
- scale: The scale factor for the image,
with a value like `1.0`, `2.0`, or `3.0`.
- orientation: The orientation of the image. The default is
``Image/Orientation/up``.
Creates an unlabeled, decorative image.
SwiftUI ignores this image for accessibility purposes.
- Parameters:
- name: The name of the image resource to lookup
- bundle: The bundle to search for the image resource. If `nil`,
SwiftUI uses the main `Bundle`. Defaults to `nil`.
Creates a system symbol image with a variable value.
This initializer creates an image using a system-provided symbol. The
rendered symbol may alter its appearance to represent the value
provided in `variableValue`. Use
[SF Symbols](https://developer.apple.com/design/resources/#sf-symbols)
(version 4.0 or later) to find system symbols that support variable
values and their corresponding names.
The following example shows the effect of creating the `"chart.bar.fill"`
symbol with different values.
HStack{
Image(systemName: "chart.bar.fill", variableValue: 0.3)
Image(systemName: "chart.bar.fill", variableValue: 0.6)
Image(systemName: "chart.bar.fill", variableValue: 1.0)
}
.font(.system(.largeTitle))
To create a custom symbol image from your app's asset
catalog, use ``Image/init(_:variableValue:bundle:)`` instead.
- Parameters:
- systemName: The name of the system symbol image.
Use the SF Symbols app to look up the names of system
symbol images.
- variableValue: An optional value between `0.0` and `1.0` that
the rendered image can use to customize its appearance, if
specified. If the symbol doesn't support variable values, this
parameter has no effect. Use the SF Symbols app to look up which
symbols support variable values.
init · iOS 13.0+
init
TypeScript
static initSystemName(systemName: string): Image
Swift declaration
init(systemName: String)
Creates a system symbol image.
This initializer creates an image using a system-provided symbol. Use
[SF Symbols](https://developer.apple.com/design/resources/#sf-symbols)
to find symbols and their corresponding names.
To create a custom symbol image from your app's asset catalog, use
``Image/init(_:bundle:)`` instead.
- Parameters:
- systemName: The name of the system symbol image.
Use the SF Symbols app to look up the names of system symbol images.
method · iOS 13.0+
antialiased
TypeScript
antialiased(isAntialiased: boolean): Image
Swift declaration
func antialiased(_ isAntialiased: Bool) -> Image
Specifies whether SwiftUI applies antialiasing when rendering
the image.
- Parameter isAntialiased: A Boolean value that specifies whether to
allow antialiasing. Pass `true` to allow antialising, `false` otherwise.
- Returns: An image with the antialiasing behavior set.
Specifies the current level of quality for rendering an
image that requires interpolation.
See the article <doc:Fitting-Images-into-Available-Space> for examples
of using `interpolation(_:)` when scaling an ``Image``.
- Parameter interpolation: The quality level, expressed as a value of
the `Interpolation` type, that SwiftUI applies when interpolating
an image.
- Returns: An image with the given interpolation value set.
Indicates whether SwiftUI renders an image as-is, or
by using a different mode.
The ``TemplateRenderingMode`` enumeration has two cases:
``TemplateRenderingMode/original`` and ``TemplateRenderingMode/template``.
The original mode renders pixels as they appear in the original source
image. Template mode renders all nontransparent pixels as the
foreground color, which you can use for purposes like creating image
masks.
The following example shows both rendering modes, as applied to an icon
image of a green circle with darker green border:
Image("dot_green")
.renderingMode(.original)
Image("dot_green")
.renderingMode(.template)
You also use `renderingMode` to produce multicolored system graphics
from the SF Symbols set. Use the ``TemplateRenderingMode/original``
mode to apply a foreground color to all parts of the symbol except
those that have a distinct color in the graphic. The following
example shows three uses of the `person.crop.circle.badge.plus` symbol
to achieve different effects:
* A default appearance with no foreground color or template rendering
mode specified. The symbol appears all black in light mode, and all
white in Dark Mode.
* The multicolor behavior achieved by using `original` template
rendering mode, along with a blue foreground color. This mode causes the
graphic to override the foreground color for distinctive parts of the
image, in this case the plus icon.
* A single-color template behavior achieved by using `template`
rendering mode with a blue foreground color. This mode applies the
foreground color to the entire image, regardless of the user's Appearance preferences.
```swift
HStack {
Image(systemName: "person.crop.circle.badge.plus")
Image(systemName: "person.crop.circle.badge.plus")
.renderingMode(.original)
.foregroundColor(.blue)
Image(systemName: "person.crop.circle.badge.plus")
.renderingMode(.template)
.foregroundColor(.blue)
}
.font(.largeTitle)
```
Use the SF Symbols app to find system images that offer the multicolor
feature. Keep in mind that some multicolor symbols use both the
foreground and accent colors.
- Parameter renderingMode: The mode SwiftUI uses to render images.
- Returns: A modified ``Image``.
Returns a new image configured with the specified allowed
dynamic range.
The following example enables HDR rendering for a specific
image view, assuming that the image has an HDR (ITU-R 2100)
color space and the output device supports it:
Image("hdr-asset").allowedDynamicRange(.high)
- Parameter range: the requested dynamic range, or nil to
restore the default allowed range.
- Returns: a new image.
Sets the rendering mode for symbol images within this view.
- Parameter mode: The symbol rendering mode to use.
- Returns: A view that uses the rendering mode you supply.
Sets the variable value mode mode for symbol images within this view.
- Parameter mode: The symbol variable value mode to use.
- Returns: A view that uses the symbol variable value mode you supply.
Sets the color rendering mode of the image.
- Parameter mode: The color rendering mode, or nil to use the
default mode.
- Returns: A view that specifies how to fill symbol images.
Initializes an image of the given size, with contents provided by a
custom rendering closure.
Use this initializer to create an image by calling drawing commands on a
``GraphicsContext`` provided to the `renderer` closure.
The following example shows a custom image created by passing a
`GraphicContext` to draw an ellipse and fill it with a gradient:
let mySize = CGSize(width: 300, height: 200)
let image = Image(size: mySize) { context in
context.fill(
Path(
ellipseIn: CGRect(origin: .zero, size: mySize)),
with: .linearGradient(
Gradient(colors: [.yellow, .orange]),
startPoint: .zero,
endPoint: CGPoint(x: mySize.width, y:mySize.height))
)
}
- Parameters:
- size: The size of the newly-created image.
- label: The label associated with the image. SwiftUI uses the label
for accessibility.
- opaque: A Boolean value that indicates whether the image is fully
opaque. This may improve performance when `true`. Don't render
non-opaque pixels to an image declared as opaque. Defaults to `false`.
- colorMode: The working color space and storage format of the image.
Defaults to ``ColorRenderingMode/nonLinear``.
- renderer: A closure to draw the contents of the image. The closure
receives a ``GraphicsContext`` as its parameter.
Sets the mode by which SwiftUI resizes an image to fit its space.
- Parameters:
- capInsets: Inset values that indicate a portion of the image that
SwiftUI doesn't resize.
- resizingMode: The mode by which SwiftUI resizes the image.
- Returns: An image, with the new resizing behavior set.
Creates a labeled image that you can use as content for controls, with
the specified label and variable value.
This initializer creates an image using a using a symbol in the
specified bundle. The rendered symbol may alter its appearance to
represent the value provided in `variableValue`.
> Note: See WWDC22 session [10158: Adopt variable color in SF
Symbols](https://developer.apple.com/wwdc22/10158/) for details on
how to create symbols that support variable values.
- Parameters:
- name: The name of the image resource to lookup.
- variableValue: An optional value between `0.0` and `1.0` that
the rendered image can use to customize its appearance, if
specified. If the symbol doesn't support variable values, this
parameter has no effect.
- bundle: The bundle to search for the image resource. If
`nil`, SwiftUI uses the main `Bundle`. Defaults to `nil`.
- label: The label associated with the image. SwiftUI uses
the label for accessibility.
Creates a labeled image that you can use as content for controls,
with a variable value.
This initializer creates an image using a using a symbol in the
specified bundle. The rendered symbol may alter its appearance to
represent the value provided in `variableValue`.
> Note: See WWDC22 session [10158: Adopt variable color in SF
Symbols](https://developer.apple.com/wwdc22/10158/) for details
on how to create symbols that support variable values.
- Parameters:
- name: The name of the image resource to lookup, as well as
the localization key with which to label the image.
- variableValue: An optional value between `0.0` and `1.0` that
the rendered image can use to customize its appearance, if
specified. If the symbol doesn't support variable values, this
parameter has no effect.
- bundle: The bundle to search for the image resource and
localization content. If `nil`, SwiftUI uses the main
`Bundle`. Defaults to `nil`.
Creates a labeled image based on a Core Graphics image instance, usable
as content for controls.
- Parameters:
- cgImage: The base graphical image.
- scale: The scale factor for the image,
with a value like `1.0`, `2.0`, or `3.0`.
- orientation: The orientation of the image. The default is
``Image/Orientation/up``.
- label: The label associated with the image. SwiftUI uses the label
for accessibility.
Creates a labeled image that you can use as content for controls, with
the specified label.
- Parameters:
- name: The name of the image resource to lookup
- bundle: The bundle to search for the image resource. If `nil`,
SwiftUI uses the main `Bundle`. Defaults to `nil`.
- label: The label associated with the image. SwiftUI uses the label
for accessibility.
Creates a labeled image that you can use as content for controls.
- Parameters:
- name: The name of the image resource to lookup, as well as the
localization key with which to label the image.
- bundle: The bundle to search for the image resource and localization
content. If `nil`, SwiftUI uses the main `Bundle`. Defaults to `nil`.
