# <image>

# Summary

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


  • Always use <image> in your code, as <img> exists only for backward compatibility reasons and may removed in the future release.
  • 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>. Ref Android adapter and iOS handler.

# Basic Usage

<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


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

# Attributes

AttributeTypeValueDefault Value
placeholderString{URL / Base64}-
resizeStringcover / contain / stretchstretch
srcString{URL / Base64 }-
autoBitmapRecycleAndroidBoolean{true / false }true


  • 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.
  • quality attribute is parsed by WeexSDK but not handled. WeexSDK will pass this value to image handler.
  • If resize property does not work as expected, the image may be clipped by image downloader. You can use "quality='original'" to solve the problem.

# 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

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)

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.


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

# autoBitmapRecycle

A boolean flag which controls whether recycle the memory of image when the image is out of the screen.

  • true for recycling the memory of image when the image is out of the screen.
  • false for not recycling the memory of image when the image is out of the screen, which may provide better user experience with more memory cost.
  • The default value is true

# Component Methods


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


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 {
    // Do something to handle failure

Complete example goes here.

# 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.

# Vue Example

# Rax Example

rax-image is the component <image> of rax, which can run in web and weex.

import { createElement, render } from 'rax';
import Driver from "driver-universal";
import Image from 'rax-image';

const App = () => {
 return (
       uri: 'https://gw.alicdn.com/tfs/TB1bBD0zCzqK1RjSZFpXXakSXXa-68-67.png',
       height: '68rpx',
       width: '67rpx'

render(<App />, document.body, { driver: Driver });

rax-image doc

Last Updated: 8/15/2022
Excellent docUnusable doc