# Titanium.UI.ImageView > A view to display a single image or series of animated images. - Source: https://titaniumsdk.com/docs/sdk/13.1.0/Titanium.UI.ImageView - Titanium SDK version: 13.1.0 - Kind: view - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 0.9 - Extends: Titanium.UI.View - Inheritance: Titanium.UI.View > Titanium.Proxy Use the [Titanium.UI.createImageView](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#createImageView) method or **``** Alloy element to create an `ImageView`. Specifying either a `width` or `height` property for this view will scale its image(s) with the aspect ratio maintained, up to a maximum size that does not exceed its parent view. #### Remote Images You can display both local and remote images in an ImageView. When loading remote images, you should set the defaultImage property to a local image, which will be displayed while the remote image is being downloaded. Remote images are cached automatically on the iOS-, Android- and Windows platform. Android Note: Android 6 and later uses runtime permissions to secure the user's privacy. Therefore, you should call [Titanium.Filesystem.requestStoragePermissions](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md#requestStoragePermissions) before attempting to load remote images. Read more about remote images and general best practices in the [Image Best Practices Guide](https://titaniumsdk.com/guide/Titanium_SDK/Titanium_SDK_Guide/Best_Practices_and_Recommendations/Image_Best_Practices.html#caching-remote-images). #### Android 9-Patch Scaled Images A nine-patch (9-patch) image is simply a standard `png` image with a transparent border of a single pixel, containing "guides" defined by solid black (`#000`) color fills. Guides added to the top and left edges determine that the image may be stretched in horizontal and vertical planes respectively. Optionally, the content area may be defined by guides added to the bottom and right edges. Although any image editor may be used to create the guides, certain settings can cause the edges of the graphic to "bleed" into the transparent border, consequently making it non-transparent. Thus, the `draw9patch` utility provided in the Android SDK tools directory is recommended for this purpose. For further information about nine-patch images and the Android utility, see the [Nine-patch](https://developer.android.com/guide/topics/graphics/drawables#nine-patch) and [Draw 9-patch](https://developer.android.com/studio/write/draw9patch) sections of the Android Developer website. The nine-patch technique may be used with any of Titanium's static image properties. See the "Button with Nine-patch Background Image" example for a demonstration. ## Example: Basic Image View In this example, we create a simple image view: ``` js Ti.UI.backgroundColor = 'white'; var win = Ti.UI.createWindow(); var image = Ti.UI.createImageView({ image:'/images/myimage.png' }); win.add(image); win.open(); ``` ## Example: Button with Nine-patch Background Image Create a button with a nine-patch image background, that swaps with another image when selected, and generates a message in the console when clicked. Note that images are referenced in the code without the `.9` part of the filename, and that the project should be cleaned to ensure that the files are correctly copied to the project. ``` js var win = Ti.UI.createWindow({ backgroundColor: 'white', exitOnClose: true, fullscreen: false, title: 'Click button to test' }); var button = Ti.UI.createButton({ backgroundImage: '/images/custom-slider-right.png', backgroundSelectedImage:'/images/custom-slider-left.png', title: 'Click me!', top: 10, width: 300, height: 200 }); button.addEventListener('click',function(e){ Ti.API.info("You clicked the button"); }); win.add(button); win.open(); ``` ## Example: Alloy XML Markup Previous basic image view example as an Alloy view. ``` xml ``` ## Properties ### animating - Type: Boolean - Platforms: Android, iPhone, iPad, macOS - Permission: read-only - Default: `false on creation, true on load (Android), false (iPhone, iPad)` Indicates whether animation is running. ### autorotate - Type: Boolean - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 3.0.0 - Default: `true` Indicates whether the image should be rotated based on EXIF orientation data. Before Titanium 10.1.0, this defaulted to `false` on Android. ### decodeRetries - Type: Number - Platforms: Android - Since: Titanium SDK 1.7.0 - Default: `2` Number of times to retry decoding the bitmap at a URL. Defaults to 2 on Titanium 10.1.0 and higher. Defaults to 5 on older SDK versions. ### defaultImage - Type: String - Platforms: Android, iPhone, iPad, macOS Local path to the default image to display while loading a remote image. ### duration - Type: Number - Platforms: Android, iPhone, iPad, macOS - Default: `200 ms in Release 2.1.1 and later. Platform-specific default in earlier releases.` Amount of time in milliseconds to animate one cycle. Starting with release 2.1.1, the minimum duration is 30 ms and the default duration is 200 ms. On Android, prior to release 2.1.1, if any images are assigned to the `images` property when the animation is started, duration will be set to the number of images multiplied by 33 ms. If no images are assigned, duration will be set to 100 ms. On iOS, prior to release 2.1.1, the default is 30 ms. On Android, if the value of duration is changed, [stop](https://titaniumsdk.com/docs/sdk/Titanium.UI.ImageView.md#stop) and [start](https://titaniumsdk.com/docs/sdk/Titanium.UI.ImageView.md#start) need to be called for the new value to take effect. ### enableZoomControls - Type: Boolean - Platforms: Android - Since: Titanium SDK 1.3.0 - Default: `false` Show zoom controls when the user touches the image view. ### hires - Type: Boolean - Platforms: iPhone, iPad, macOS - Default: `false` Set to `true` to prevent scaling of 2x/3x-resolution remote images for retina displays. Causes images to display at 50%, where one pixel of the graphic maps to one physical pixel on-screen. This functionality is automatically determined for local images via their filenames, and thus this property is only applicable to remote images. ### image - Type: String | Titanium.Blob | Titanium.Filesystem.File - Platforms: Android, iPhone, iPad, macOS Image to display. Image to display, defined using a local filesystem path, a `File` object, a remote URL, or a `Blob` object containing image data. For Android, if there is a redirect and change in protocol, it will not follow. For example, from http to https and vice versa. See [Java Bug Database](http://bugs.java.com/bugdatabase/view_bug.do?bug_id=4620571) for more information. ### images - Type: Array | Array | Array - Platforms: Android, iPhone, iPad, macOS Array of images to animate, defined using local filesystem paths, `File` objects, remote URLs (Android only), or `Blob` objects containing image data. When using this property, an initial `start()` needs to be called upon the ImageView before any image will show in this imageview. Related properties/methods to look at: `start`, `stop`, `pause`, `reverse`, `resume` and `repeatCount` ### imageTouchFeedback - Type: Boolean - Platforms: Android - Since: Titanium SDK 10.1.0 - Default: `false` Enables a ripple effect when the foreground image is touched. Note that the [touchFeedback](https://titaniumsdk.com/docs/sdk/Titanium.UI.View.md#touchFeedback) property applies a ripple effect to the view's background. If the image is opaque and completely covers the view (such as a photo), then the background's ripple won't be visible. In this case, you should use this `imageTouchFeedback` property to apply a ripple effect to the foreground image assigned via the `image` property. ### imageTouchFeedbackColor - Type: String - Platforms: Android - Since: Titanium SDK 10.1.0 Optional touch feedback ripple color. This has no effect unless `imageTouchFeedback` is true. Defaults to provided theme color. ### paused - Type: Boolean - Platforms: Android, iPhone, iPad, macOS - Permission: read-only - Default: `false` Indicates whether the animation is paused. ### preventDefaultImage - Type: Boolean - Platforms: iPhone, iPad, macOS - Default: `false` Prevent the default image from being displayed while loading a remote image. This property is ignored when the `defaultImage` property is set. ### repeatCount - Type: Number - Platforms: Android, iPhone, iPad, macOS - Default: `0 (infinite)` Number of times to repeat the image animation. ### reverse - Type: Boolean - Platforms: Android, iPhone, iPad, macOS - Default: `false` Run the animation in reverse. ### scalingMode - Type: Number - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 10.1.0 - Default: `` Determines how the image is scaled within the view. Accepts: `Titanium.Media.IMAGE_SCALING_ASPECT_FILL`, `Titanium.Media.IMAGE_SCALING_ASPECT_FIT`, `Titanium.Media.IMAGE_SCALING_AUTO`, `Titanium.Media.IMAGE_SCALING_FILL`, `Titanium.Media.IMAGE_SCALING_NONE` ### tintColor - Type: String | Titanium.UI.Color - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 5.4.0 - Default: `null` The view's tintColor. Android does not support setting instances of [Titanium.UI.Color](https://titaniumsdk.com/docs/sdk/Titanium.UI.Color.md) ## Methods ### addSymbolEffect - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 12.4.0 - Requires: iOS 17.0+ Adds a symbol effect to the image view with specified options, animation, and callback. Parameters: - `symbolEffect` (String): The symbol effect to add. One of `pulse`, `bounce`, `appear`, `disappear`, `variableColor` or `scale`. - `options` (String): The options for the symbol effect. One of `repeating`, `nonRepeating`, `repeatCount` or `speed`. - `animated` (Boolean): A Boolean value that indicates whether to animate the addition of a `scale`, `appear`, or `disappear` effect. Default: `false`. - `callback` (Callback): A callback the system calls after the effect’s addition is complete. ### pause - Platforms: Android, iPhone, iPad, macOS Pauses a running animation. Use `resume` method to continue. This method only works if multiple images are specified. ### resume - Platforms: Android, iPhone, iPad, macOS Resumes an animation from a `pause` state. This method only works if multiple images are specified. ### start - Platforms: Android, iPhone, iPad, macOS Starts the image animation. On Android, also resets `index` to the first image. This method only works if multiple images are specified. ### stop - Platforms: Android, iPhone, iPad, macOS Stops a running animation. On iOS, also resets `index` to the first image. This method only works if multiple images are specified. ### toBlob - Platforms: Android, iPhone, iPad, macOS Returns the image as a Blob object. Returns: Titanium.Blob ## Events ### change - Platforms: Android, iPhone, iPad, macOS Fired for each frame change during an animation. Event properties: - `index` (Number): Index of the image frame being displayed. ### error - Platforms: Android, iPhone, iPad, macOS Fired when an image fails to load. Event properties: - `success` (Boolean): Indicates a successful operation. Returns `false`. - `error` (String): Error message, if any returned. May be undefined. - `code` (Number): Error code. If the error was generated by the operating system, that system's error value is used. Otherwise, this value will be -1. - `image` (String): URL of the image that failed to load. ### load - Platforms: Android, iPhone, iPad, macOS Fired when either the initial image and/or all of the images in an animation are loaded. Event properties: - `state` (String): Set to `image` when the image defined in the [image](https://titaniumsdk.com/docs/sdk/Titanium.UI.ImageView.md#image) property is loaded. Set to `images`, when the series of images defined in the [images](https://titaniumsdk.com/docs/sdk/Titanium.UI.ImageView.md#images) property are loaded. ### pause - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 2.1.1 Fired when the animation pauses. ### start - Platforms: Android, iPhone, iPad, macOS Fired when the animation starts. ### stop - Platforms: Android, iPhone, iPad, macOS Fired when the animation stops. ## Inherited members 99 members are inherited. Each is documented on the type that declares it. - [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/13.1.0/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener` - [Titanium.UI.View](https://titaniumsdk.com/docs/sdk/13.1.0/Titanium.UI.View.md): `accessibilityDisableLongPress`, `accessibilityHidden`, `accessibilityHint`, `accessibilityLabel`, `accessibilityValue`, `anchorPoint`, `animate`, `animatedCenter`, `backgroundColor`, `backgroundDisabledColor`, `backgroundDisabledImage`, `backgroundFocusedColor`, `backgroundFocusedImage`, `backgroundGradient`, `backgroundImage`, `backgroundLeftCap`, `backgroundRepeat`, `backgroundSelectedColor`, `backgroundSelectedImage`, `backgroundTopCap`, `borderColor`, `borderRadius`, `borderWidth`, `bottom`, `center`, `clearMotionEffects`, `click`, `clipMode`, `convertPointToView`, `dblclick`, `doubletap`, `elevation`, `filterTouchesWhenObscured`, `focus`, `focusable`, `getViewById`, `height`, `hiddenBehavior`, `hide`, `horizontalMotionEffect`, `horizontalWrap`, `id`, `insertAt`, `keepScreenOn`, `keypressed`, `layout`, `left`, `longclick`, `longpress`, `opacity`, `overrideCurrentAnimation`, `pinch`, `postlayout`, `previewContext`, `pullBackgroundColor`, `rect`, `right`, `rotate`, `rotation`, `rotationX`, `rotationY`, `scaleX`, `scaleY`, `show`, `singletap`, `size`, `softKeyboardOnFocus`, `stopAnimation`, `swipe`, `toImage`, `tooltip`, `top`, `touchEnabled`, `touchFeedback`, `touchFeedbackColor`, `touchcancel`, `touchend`, `touchmove`, `touchstart`, `transform`, `transitionName`, `translationX`, `translationY`, `translationZ`, `twofingertap`, `verticalMotionEffect`, `viewShadowColor`, `viewShadowOffset`, `viewShadowRadius`, `visible`, `width`, `zIndex` --- - This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1. - Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.