# UIImage An object that manages image data in your app. ``` class UIImage ``` ## Overview You use image objects to represent image data of all kinds, and the [`UIImage`](/documentation/UIKit/UIImage) class is capable of managing data for all image formats supported by the underlying platform. Image objects are immutable, so you always create them from existing image data, such as an image file on disk or programmatically created image data. An image object may contain a single image or a sequence of images for use in an animation. You can use image objects in several different ways: - Assign an image to a [`UIImageView`](/documentation/UIKit/UIImageView) object to display the image in your interface. - Use an image to customize system controls such as buttons, sliders, and segmented controls. - Draw an image directly into a view or other graphics context. - Pass an image to other APIs that might require image data. Although image objects support all platform-native image formats, it’s recommended that you use PNG or JPEG files for most images in your app. Image objects are optimized for reading and displaying both formats, and those formats offer better performance than most other image formats. Because the PNG format is lossless, it’s especially recommended for the images you use in your app’s interface. ### Create image objects When creating image objects using the methods of this class, you must have existing image data located in a file or data structure. You can’t create an empty image and draw content into it. There are many options for creating image objects, each of which is best for specific situations: - Use the [`init(named:in:compatibleWith:)`](/documentation/UIKit/UIImage/init(named:in:compatibleWith:)) method (or the [`init(named:)`](/documentation/UIKit/UIImage/init(named:)) method) to create an image from an image asset or image file located in your app’s main bundle (or some other known bundle). Because these methods cache the image data automatically, they’re especially recommended for images that you use frequently. - Use the [`imageWithContentsOfFile:`](/documentation/UIKit/UIImage/imageWithContentsOfFile:) or [`init(contentsOfFile:)`](/documentation/UIKit/UIImage/init(contentsOfFile:)) method to create an image object where the initial data isn’t in a bundle. These methods load the image data from disk each time, so don’t use them to load the same image repeatedly. - Use the [`animatedImage(with:duration:)`](/documentation/UIKit/UIImage/animatedImage(with:duration:)) and [`animatedImageNamed(_:duration:)`](/documentation/UIKit/UIImage/animatedImageNamed(_:duration:)) methods to create a single [`UIImage`](/documentation/UIKit/UIImage) object comprised of multiple sequential images. Install the resulting image in a [`UIImageView`](/documentation/UIKit/UIImageView) object to create animations in your interface. Other methods of the [`UIImage`](/documentation/UIKit/UIImage) class let you create animations from specific types of data, such as Core Graphics images or image data you create yourself. UIKit also provides the [`UIGraphicsGetImageFromCurrentImageContext()`](/documentation/UIKit/UIGraphicsGetImageFromCurrentImageContext()) function to create images from content you draw yourself. You use that function in conjunction with a bitmap-based graphics context, which you use to capture your drawing commands. > Note: > Because image objects are immutable, you can’t change their properties after creation. Most image properties are set automatically using metadata in the accompanying image file or image data. The immutable nature of image objects also means they’re safe to create and use from any thread. Image assets are the easiest way to manage the images that ship with your app. Each new Xcode project contains an assets library, to which you can add multiple image sets. An image set contains the variations of a single image that your app uses. A single image set can provide different versions of an image for different platforms, for different trait environments (compact or regular), and for different scale factors. In addition to loading images from disk, you can ask the user to supply images from an available camera or photo library using a [`UIImagePickerController`](/documentation/UIKit/UIImagePickerController) object. An image picker displays a custom user interface for selecting images. Accessing user-supplied images requires explicit user permission. For more information about using an image picker, see [`UIImagePickerController`](/documentation/UIKit/UIImagePickerController). ### Define a stretchable image A stretchable image is one that defines regions where you can duplicate the underlying image data in an aesthetically pleasing way. Stretchable images are commonly used to create backgrounds that can grow or shrink to fill the available space. Define a stretchable image by adding insets to an existing image using the [`resizableImage(withCapInsets:)`](/documentation/UIKit/UIImage/resizableImage(withCapInsets:)) or [`resizableImage(withCapInsets:resizingMode:)`](/documentation/UIKit/UIImage/resizableImage(withCapInsets:resizingMode:)) method. The insets subdivide the image into two or more parts. Specifying nonzero values for each inset yields an image divided into nine parts, as shown in the following image:  Each inset defines the portion of the image that doesn’t stretch in the given dimension. The regions inside an image’s top and bottom insets maintain a fixed height, and the areas inside the left and right insets maintain a fixed width. The following image shows how each part of a nine-part image stretches as the image itself is stretched to fill the available space. The corners of the image don’t change size because they’re inside both a horizontal and vertical inset:  ### Compare images The method is the only reliable way to determine whether two image objects contain the same image data. The following code illustrates the correct and incorrect ways to compare images. ```objc // Load the same image twice. UIImage* image1 = [UIImage imageNamed:@"MyImage"]; UIImage* image2 = [UIImage imageNamed:@"MyImage"]; // The image objects may be different, but the contents are still equal if ([image1 isEqual:image2]) { // Correct. This technique compares the image data correctly. } if (image1 == image2) { // Incorrect! Direct object comparisons may not work. } ``` ### Access the image data Image objects don’t provide direct access to their underlying image data. However, you can retrieve the image data in other formats for use in your app. Specifically, you can use the [`cgImage`](/documentation/UIKit/UIImage/cgImage) and [`ciImage`](/documentation/UIKit/UIImage/ciImage) properties to retrieve versions of the image that are compatible with Core Graphics and Core Image, respectively. You can also use the [`pngData()`](/documentation/UIKit/UIImage/pngData()) and [`jpegData(compressionQuality:)`](/documentation/UIKit/UIImage/jpegData(compressionQuality:)) functions to generate an object containing the image data in either the PNG or JPEG format. ## Topics ### Loading and caching images [Providing images for different appearances](/documentation/UIKit/providing-images-for-different-appearances) Supply image resources appropriate for light and dark appearances and for high-contrast environments. [Configuring and displaying symbol images in your UI](/documentation/UIKit/configuring-and-displaying-symbol-images-in-your-ui) Create scalable images that integrate with your app’s text, and adjust the appearance of those images dynamically. [Creating custom symbol images for your app](/documentation/UIKit/creating-custom-symbol-images-for-your-app) Create, organize, and annotate symbol images using SF Symbols. [`init(named:in:compatibleWith:)`](/documentation/UIKit/UIImage/init(named:in:compatibleWith:)) Creates an image object using the named image asset that’s compatible with the specified trait collection. [`init(named:in:with:)`](/documentation/UIKit/UIImage/init(named:in:with:)) Creates an image by using the named image asset that’s compatible with the configuration you specify. [`init(named:in:variableValue:configuration:)`](/documentation/UIKit/UIImage/init(named:in:variableValue:configuration:)) Creates an image by using the name, configuration, and variable value you specify. [`imageNamed:inBundle:variableValue:withConfiguration:`](/documentation/UIKit/UIImage/imageNamed:inBundle:variableValue:withConfiguration:) Creates an image by using the name, configuration, and variable value you specify. [`init(named:)`](/documentation/UIKit/UIImage/init(named:)) Creates an image object from the specified named asset. [`init(imageLiteralResourceName:)`](/documentation/UIKit/UIImage/init(imageLiteralResourceName:)) Returns the image object for the specified resource. [`init(systemName:withConfiguration:)`](/documentation/UIKit/UIImage/init(systemName:withConfiguration:)) Creates an image object that contains a system symbol image with the specified configuration. [`init(systemName:variableValue:configuration:)`](/documentation/UIKit/UIImage/init(systemName:variableValue:configuration:)) Creates an image object that contains a system symbol image with the configuration and variable value you specify. [`systemImageNamed:variableValue:withConfiguration:`](/documentation/UIKit/UIImage/systemImageNamed:variableValue:withConfiguration:) Creates an image object that contains a system symbol image with the configuration and variable value you specify. [`init(systemName:compatibleWith:)`](/documentation/UIKit/UIImage/init(systemName:compatibleWith:)) Creates an image object that contains a system symbol image appropriate for the specified traits. [`init(systemName:)`](/documentation/UIKit/UIImage/init(systemName:)) Creates an image object that contains a system symbol image. [`init(resource:)`](/documentation/UIKit/UIImage/init(resource:)) [Building high-performance lists and collection views](/documentation/UIKit/building-high-performance-lists-and-collection-views) Improve the performance of lists and collections in your app with prefetching and image preparation. ### Loading images for display [`preparingForDisplay()`](/documentation/UIKit/UIImage/preparingForDisplay()) Decodes an image synchronously and provides a new one for display in views and animations. [`prepareForDisplay(completionHandler:)`](/documentation/UIKit/UIImage/prepareForDisplay(completionHandler:)) Decodes an image asynchronously and provides a new one for display in views and animations. [`preparingThumbnail(of:)`](/documentation/UIKit/UIImage/preparingThumbnail(of:)) Returns a new thumbnail image at the specified size. [`prepareThumbnail(of:completionHandler:)`](/documentation/UIKit/UIImage/prepareThumbnail(of:completionHandler:)) Creates a thumbnail image at the specified size asynchronously on a background thread. ### Creating and initializing image objects [`imageWithContentsOfFile:`](/documentation/UIKit/UIImage/imageWithContentsOfFile:) Creates and returns an image object by loading the image data from the file at the specified path. [`imageWithData:`](/documentation/UIKit/UIImage/imageWithData:) Creates and returns an image object that uses the specified image data. [`imageWithData:scale:`](/documentation/UIKit/UIImage/imageWithData:scale:) Creates and returns an image object that uses the specified image data and scale factor. [`imageWithCGImage:`](/documentation/UIKit/UIImage/imageWithCGImage:) Creates and returns an image object representing the specified Quartz image. [`imageWithCGImage:scale:orientation:`](/documentation/UIKit/UIImage/imageWithCGImage:scale:orientation:) Creates and returns an image object with the specified scale and orientation factors. [`imageWithCIImage:`](/documentation/UIKit/UIImage/imageWithCIImage:) Creates and returns an image object that contains a Core Image object. [`imageWithCIImage:scale:orientation:`](/documentation/UIKit/UIImage/imageWithCIImage:scale:orientation:) Creates and returns an image object based on a Core Image object and the specified attributes. [`init(contentsOfFile:)`](/documentation/UIKit/UIImage/init(contentsOfFile:)) Initializes and returns the image object with the contents of the specified file. [`init(data:)`](/documentation/UIKit/UIImage/init(data:)) Initializes and returns the image object with the specified data. [`init(data:scale:)`](/documentation/UIKit/UIImage/init(data:scale:)) Initializes and returns the image object with the specified data and scale factor. [`init(cgImage:)`](/documentation/UIKit/UIImage/init(cgImage:)-14qlb) Initializes and returns the image object with the specified Quartz image reference. [`init(cgImage:scale:orientation:)`](/documentation/UIKit/UIImage/init(cgImage:scale:orientation:)-2ouhh) Initializes and returns an image object with the specified scale and orientation factors. [`init(ciImage:)`](/documentation/UIKit/UIImage/init(ciImage:)-93vu1) Initializes and returns an image object with the specified Core Image object. [`init(ciImage:scale:orientation:)`](/documentation/UIKit/UIImage/init(ciImage:scale:orientation:)-9gpyn) Initializes and returns an image object with the specified Core Image object and properties. [`UIImageReader`](/documentation/UIKit/UIImageReader-swift.struct) [`UIImageReader`](/documentation/UIKit/UIImageReader-c.class) [`UIImageReaderConfiguration`](/documentation/UIKit/UIImageReaderConfiguration) The properties that a reader uses to decode images. ### Creating animated images [`animatedImageNamed(_:duration:)`](/documentation/UIKit/UIImage/animatedImageNamed(_:duration:)) Creates and returns an animated image. [`animatedImage(with:duration:)`](/documentation/UIKit/UIImage/animatedImage(with:duration:)) Creates and returns an animated image from an existing set of images. [`animatedResizableImageNamed(_:capInsets:duration:)`](/documentation/UIKit/UIImage/animatedResizableImageNamed(_:capInsets:duration:)) Creates and returns an animated image with end caps. [`animatedResizableImageNamed(_:capInsets:resizingMode:duration:)`](/documentation/UIKit/UIImage/animatedResizableImageNamed(_:capInsets:resizingMode:duration:)) Creates and returns an animated image with end caps and a specific resizing mode. ### Changing the image attributes [`withConfiguration(_:)`](/documentation/UIKit/UIImage/withConfiguration(_:)) Returns a new version of the current image, replacing the current configuration attributes with the specified attributes. [`applyingSymbolConfiguration(_:)`](/documentation/UIKit/UIImage/applyingSymbolConfiguration(_:)) Returns a new version of the current image, applying the specified configuration attributes on top of the current attributes. [`imageFlippedForRightToLeftLayoutDirection()`](/documentation/UIKit/UIImage/imageFlippedForRightToLeftLayoutDirection()) Returns a new version of the current image that flips horizontally when it’s in a right-to-left layout. [`withHorizontallyFlippedOrientation()`](/documentation/UIKit/UIImage/withHorizontallyFlippedOrientation()) Returns a new version of the image that’s a mirror of the original image. [`withRenderingMode(_:)`](/documentation/UIKit/UIImage/withRenderingMode(_:)) Returns a new version of the image that uses the specified rendering mode. [`withAlignmentRectInsets(_:)`](/documentation/UIKit/UIImage/withAlignmentRectInsets(_:)) Returns a new version of the image that uses the specified alignment insets. [`resizableImage(withCapInsets:)`](/documentation/UIKit/UIImage/resizableImage(withCapInsets:)) Returns a new version of the image with the specified cap insets. [`resizableImage(withCapInsets:resizingMode:)`](/documentation/UIKit/UIImage/resizableImage(withCapInsets:resizingMode:)) Returns a new version of the image with the specified cap insets and options. [`imageWithoutBaseline()`](/documentation/UIKit/UIImage/imageWithoutBaseline()) Creates a copy of the current image object without any baseline information. [`withBaselineOffset(fromBottom:)`](/documentation/UIKit/UIImage/withBaselineOffset(fromBottom:)) Creates a new image with a baseline at the specified offset from the bottom of the image. [`UIImage.Configuration`](/documentation/UIKit/UIImage/Configuration-swift.class) A configuration object that contains the traits that the system uses when selecting the current image variant. [`UIImage.SymbolConfiguration`](/documentation/UIKit/UIImage/SymbolConfiguration-swift.class) An object that contains the specific font, size, style, and weight attributes to apply to a symbol image. ### Getting standard system images [`add`](/documentation/UIKit/UIImage/add) The standard image for indicating the addition of content. [`remove`](/documentation/UIKit/UIImage/remove) The standard image for indicating the removal of content. [`actions`](/documentation/UIKit/UIImage/actions) The standard image for indicating user-initiated actions. [`checkmark`](/documentation/UIKit/UIImage/checkmark) The standard image for a checkmark on a filled-circle background. [`strokedCheckmark`](/documentation/UIKit/UIImage/strokedCheckmark) The standard image for a checkmark on a tinted circle with a white-stroked border. ### Getting the image data [`cgImage`](/documentation/UIKit/UIImage/cgImage) The underlying Quartz image data. [`ciImage`](/documentation/UIKit/UIImage/ciImage) The underlying Core Image data. [`images`](/documentation/UIKit/UIImage/images) The complete array of image objects that compose the animation of an animated object. [`imageAsset`](/documentation/UIKit/UIImage/imageAsset) The image asset (if any) for the image. ### Getting the image size and scale [`scale`](/documentation/UIKit/UIImage/scale) The scale factor of the image. [`size`](/documentation/UIKit/UIImage/size) The logical dimensions, in points, for the image. ### Accessing image attributes [`imageOrientation`](/documentation/UIKit/UIImage/imageOrientation) The orientation of the receiver’s image. [`UIImage.Orientation`](/documentation/UIKit/UIImage/Orientation) Constants that specify the intended display orientation for an image. [`flipsForRightToLeftLayoutDirection`](/documentation/UIKit/UIImage/flipsForRightToLeftLayoutDirection) A Boolean value that indicates whether the image flips in a right-to-left layout. [`resizingMode`](/documentation/UIKit/UIImage/resizingMode-swift.property) The resizing mode of the image. [`UIImage.ResizingMode`](/documentation/UIKit/UIImage/ResizingMode-swift.enum) Constants that specify the possible resizing modes for an image. [`duration`](/documentation/UIKit/UIImage/duration) The time interval for displaying an animated image. [`capInsets`](/documentation/UIKit/UIImage/capInsets) The end-cap insets. [`alignmentRectInsets`](/documentation/UIKit/UIImage/alignmentRectInsets) The alignment metadata for positioning the image during layout. [`isSymbolImage`](/documentation/UIKit/UIImage/isSymbolImage) A Boolean value that indicates whether the image is a symbol. ### Getting the image configuration [`configuration`](/documentation/UIKit/UIImage/configuration-swift.property) The configuration details for the image. [`symbolConfiguration`](/documentation/UIKit/UIImage/symbolConfiguration-swift.property) The configuration details for a symbol image. [`traitCollection`](/documentation/UIKit/UIImage/traitCollection) The trait collection that describes the current variant of the image. ### Specifying the dynamic range [`isHighDynamicRange`](/documentation/UIKit/UIImage/isHighDynamicRange) Indicates that this image is tagged for display of high dynamic range content. [`imageRestrictedToStandardDynamicRange()`](/documentation/UIKit/UIImage/imageRestrictedToStandardDynamicRange()) Returns a new image that will render within the standard range. [`heicData()`](/documentation/UIKit/UIImage/heicData()) Returns HEIC data representing the image, or nil if such a representation could not be generated. HEIC is recommended for efficiently storing all kinds of images, including those with high dynamic range content. [`UIImage.DynamicRange`](/documentation/UIKit/UIImage/DynamicRange) ### Managing the baseline [`baselineOffsetFromBottom`](/documentation/UIKit/UIImage/baselineOffsetFromBottom-3emg) The position of the baseline relative to the bottom of the image. [`hasBaseline`](/documentation/UIKit/UIImage/hasBaseline) A Boolean value that indicates whether the image has a defined baseline offset. [`baselineOffsetFromBottom`](/documentation/UIKit/UIImage/baselineOffsetFromBottom-23gkf) The position of the baseline relative to the bottom of the image. ### Getting rendering information [`renderingMode`](/documentation/UIKit/UIImage/renderingMode-swift.property) A setting that determines how the app renders an image. [`UIImage.RenderingMode`](/documentation/UIKit/UIImage/RenderingMode-swift.enum) Constants that specify the possible rendering modes for an image. [`imageRendererFormat`](/documentation/UIKit/UIImage/imageRendererFormat) The preferred image renderer format for the image. ### Tinting the image [`withTintColor(_:)`](/documentation/UIKit/UIImage/withTintColor(_:)) Returns a new version of the current image with the specified tint color. [`withTintColor(_:renderingMode:)`](/documentation/UIKit/UIImage/withTintColor(_:renderingMode:)) Returns a new version of the image with a tint color that uses the specified rendering mode. ### Drawing images [`draw(at:)`](/documentation/UIKit/UIImage/draw(at:)) Draws the image at the specified point in the current context. [`draw(at:blendMode:alpha:)`](/documentation/UIKit/UIImage/draw(at:blendMode:alpha:)) Draws the entire image at the specified point using the custom compositing options. [`draw(in:)`](/documentation/UIKit/UIImage/draw(in:)) Draws the entire image in the specified rectangle, scaling it as necessary to fit. [`draw(in:blendMode:alpha:)`](/documentation/UIKit/UIImage/draw(in:blendMode:alpha:)) Draws the entire image in the specified rectangle using the specified compositing options. [`drawAsPattern(in:)`](/documentation/UIKit/UIImage/drawAsPattern(in:)) Draws a tiled Quartz pattern using the receiver’s contents as the tile pattern. ### Exporting standard bitmap formats [`jpegData(compressionQuality:)`](/documentation/UIKit/UIImage/jpegData(compressionQuality:)) Returns a data object that contains the image in JPEG format. [`pngData()`](/documentation/UIKit/UIImage/pngData()) Returns a data object that contains the specified image in PNG format. ### Deprecated [`stretchableImage(withLeftCapWidth:topCapHeight:)`](/documentation/UIKit/UIImage/stretchableImage(withLeftCapWidth:topCapHeight:)) Creates and returns a new image object with the specified cap values. [`leftCapWidth`](/documentation/UIKit/UIImage/leftCapWidth) The horizontal end-cap size. [`topCapHeight`](/documentation/UIKit/UIImage/topCapHeight) The vertical end-cap size. --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)