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

Note: <img> element which is usually used in HTML is not supported in Weex, you should use <image> instead.

Note: Weex doesn’t have built-in image downloader, as download, cache, decompression features are complicated and some open source tools like SDWebImage handles it well, so please add native image adapter/handler before using <image>.

See also: Android adapter and iOS handler.

Basic Usage#

Note: the style attributes of width and height must be specified, otherwise it won’t work.

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

See the example.


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.


A URL value for placeholder image. It will be displayed when the image view is empty and will be replaced as soon as the ‘src’ image gets loaded.(Example)


image resize property

  • 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)

See also: background-size.


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.

Component Methods#

save v0.16.0+#

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


  • 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 hanlde success
} else {
// Do something to hanlde failure

Complete example goes here.


Support common events.


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.


Support common styles.

Usage Notes#

  • Add image adapter/handler before using <image>
  • The width and height in the styles of <image> must be specified.
  • <image> can not have any nested child component.


Edit this page on GitHub