---

title: type: references group: Build-in Components order: 8.04 version: 2.1

<image> is used to display a single image in your interface.

Note: Always use <image> in your code, as <img> exists only for backward compatibility reasons and may removed in the future release.

Note: Weex doesn't have built-in library for image downloading and caching, as there are some great open source library like SDWebImage in iOS and Picasso in Android handling these problem, so please add native image adapter/handler before using <image>.

See also: Android adapter and iOS handler.

Basic Usage

Note: the style of width, height and src must be specified, otherwise it will load nothing.

<image style="width:500px;height:500px" src="https://vuejs.org/images/logo.png"></image>

See the example.

Child

<image> doesn't support any child component.

Styles

Support common styles.

Attributes

Attribute	Type	Value	Default Value
placeholder	String	{URL / Base64}	-
resize	String	cover / contain / stretch	stretch
src	String	{URL / Base64 }	-

Note: you can specify a relative URL for src and placeholder, relative URL will be rewritten to the to the actual resource URL (local or remote). See also: Path.

placeholder

A URL value for placeholder image. It will be displayed during image downloading and replaced as soon as the image gets loaded.(Example)

resize

• contain: Scales the image as large as possible without cropping or stretching it. Remaining area within bounds is transparent (Example)

• cover: Scales the image as large as possible without stretching it. If the proportions of the image differ from the element, it is cropped either vertically or horizontally so that no empty space remains. (Example)

• stretch: Default value. Scales the content to fit the size of the element itself by changing the aspect ratio of the image if necessary. (Example)

resize property is similar to background-size.

src

The URL of the image to display. This attribute is mandatory for the <image> component.

Supported Image Formats

Weex doesn't give a list of image formats that must be supported, it mainly relies on the image adapter/handler you are using. For example, if you are using SDWebImage as the image adapter on iOS, you can use image formats like JPEG, PNG, GIF, WebP, etc.

Note: The default image adapter on Android doesn't support gif.

Component Methods

save v0.16.0+

Save <image> content to the local device or photo album, this operation may require device permission.

Parameters:

• callback: {Function} A function which is called after the image has been saved to the local device or photo album. Callback parameters:
  • result: {Object} Callback result whose properties are:
    • success: {Boolean} A flag indicating whether the image has been saved completed.
    • errorDesc: {String} A string containing the description of the error if image is not written successfully.

Return value: null

Note: You must add NSPhotoLibraryAddUsageDescription and NSPhotoLibraryAddUsageDescription (iOS 11) to enable the access permission of the iOS photo album. See also: Cocoa Keys.

Use save Method

Add ref attribute (Vue.js Child Component Refs) on <image>:

<image ref="poster" src="path/to/image.png"></image>

Get the component reference and use the save method:

const $image = this.$refs.poster
$image.save(result => {
  if (result.success) {
    // Do something to handle success
  } else {
    console.log(result.errorDesc)
    // Do something to handle failure
  }
})

Complete example goes here.

Events

Support common events.

load

load event handler will be called when the image is loaded.

Event object:

• success: {Boolean} It shows that whether the image is loaded successfully.
• size: {Object} The loaded image size whose properties are:
  • naturalWidth: {Number} The intrinsic width of image displayed on device, it will be zero if the specified image cannot be loaded correctly.
  • naturalHeight: {Number} the intrinsic height of image displayed on device, it will be zero if the specified image cannot be loaded correctly.

Handle load Event

Bind load event on <image>:

<image @load="onImageLoad" src="path/to/image.png"></image>

Add event handler:

export default {
  methods: {
    onImageLoad (event) {
      if (event.success) {
        // Do something to hanlde success
      }
    }
  }
}

Complete example goes here.

Examples

• Base64 example
• Lazy load image example