Image

An image container that supports preview, lazy loading, custom placeholders, load failure fallback, and more.

Basic Usage

Use fit to set the image fitting style within the container, equivalent to the native object-fit property.

fill

contain

cover

none

scale-down

<template>
  <div flex>
    <div v-for="fit in fitList" :key="fit" style="flex: 1; padding: 10px">
      <div style="width: 100px; height: 80px; border: 1px solid #eee">
        <b-image :src="url" :fit="fit" width="100px" height="80px" :alt="fit"></b-image>
      </div>
      <p>{{ fit }}</p>
    </div>
  </div>
</template>

<script setup>
const url = 'https://file.iviewui.com/images/image-demo-3.jpg'
const fitList = ['fill', 'contain', 'cover', 'none', 'scale-down']
</script>

Loading

Loading placeholder text or content can be customized.

Default

Slot

<template>
  <b-row gutter="20">
    <b-col span="12">
      <b-image src="https://wangbin3162.github.io/bin-files/bg/bg2.jpg" />
      <p class="t-center">Default</p>
    </b-col>
    <b-col span="12">
      <b-image src="https://wangbin3162.github.io/bin-files/bg/bg3.jpg">
        <template #placeholder>
          <b-loading fix />
        </template>
      </b-image>
      <p class="t-center">Slot</p>
    </b-col>
  </b-row>
</template>

Load Failure

A placeholder can be set for when the image fails to load.

Default

Slot

<template>
  <b-row gutter="20">
    <b-col span="12">
      <div flex="main:center">
        <b-image width="200px" height="100px" />
      </div>
      <p class="t-center">Default</p>
    </b-col>
    <b-col span="12">
      <div flex="main:center">
        <b-image width="200px" height="100px">
          <template #error>
            <b-icon name="image" size="28" color="var(--bin-fill-color-4)" />
          </template>
        </b-image>
      </div>
      <p class="t-center">Slot</p>
    </b-col>
  </b-row>
</template>

Lazy Loading

Set lazy to enable lazy loading. Images will only load when they become visible.

Use scroll-container to specify the scroll container. If not set, the closest parent with overflow: auto or overflow: scroll will be used.

Vertical

Horizontal

<template>
  <b-row gutter="20">
    <b-col span="12">
      <div class="demo-image-lazy-vertical">
        <b-image v-for="url in vUrlList" :key="url" :src="url" lazy />
      </div>
      <p class="t-center">Vertical</p>
    </b-col>
    <b-col span="12">
      <div flex="main:center">
        <div class="demo-image-lazy">
          <div class="demo-image-lazy-inner">
            <b-image v-for="url in hUrlList" :key="url" :src="url" lazy />
          </div>
        </div>
      </div>
      <p class="t-center">Horizontal</p>
    </b-col>
  </b-row>
</template>

<script setup>
const vUrlList = [
  'https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg',
  'https://fuss10.elemecdn.com/1/34/19aa98b1fcb2781c4fba33d850549jpeg.jpeg',
  'https://fuss10.elemecdn.com/0/6f/e35ff375812e6b0020b6b4e8f9583jpeg.jpeg',
  'https://fuss10.elemecdn.com/9/bb/e27858e973f5d7d3904835f46abbdjpeg.jpeg',
  'https://fuss10.elemecdn.com/d/e6/c4d93a3805b3ce3f323f7974e6f78jpeg.jpeg',
  'https://fuss10.elemecdn.com/3/28/bbf893f792f03a54408b3b7a7ebf0jpeg.jpeg',
  'https://fuss10.elemecdn.com/2/11/6535bcfb26e4c79b48ddde44f4b6fjpeg.jpeg'
]
const hUrlList = [
  'https://file.iviewui.com/images/image-demo-1.jpg',
  'https://file.iviewui.com/images/image-demo-2.jpg',
  'https://file.iviewui.com/images/image-demo-3.jpg',
  'https://file.iviewui.com/images/image-demo-4.jpg',
  'https://file.iviewui.com/images/image-demo-5.jpg',
  'https://file.iviewui.com/images/image-demo-6.jpg'
]
</script>

<style scoped>
.demo-image-lazy-vertical {
  height: 300px;
  overflow-y: auto;
  .bin-image {
    display: block;
    min-height: 200px;
  }
}

.demo-image-lazy {
  width: 400px;
  height: 200px;
  overflow: hidden;
  overflow-x: scroll;
  .demo-image-lazy-inner {
    width: 3000px;
    height: 200px;
  }
  .bin-image {
    float: left;
    width: 400px;
    height: 200px;
  }
}
</style>

Preview

Set preview to enable image preview mode. Use preview-list to set the image list, and initial-index to set the initial image index when the preview opens.

During preview: use ← / → to switch images, ↑ / ↓ to zoom, Space to show 1:1 size, ESC to exit preview.

<template>
  <b-space>
    <template v-for="(url, index) in urlList" :key="url">
      <b-image
        :src="url"
        fit="contain"
        width="120px"
        height="80px"
        preview
        :preview-list="urlList"
        :initial-index="index"
      />
    </template>
  </b-space>
</template>

<script setup>
const urlList = [
  'https://file.iviewui.com/images/image-demo-1.jpg',
  'https://file.iviewui.com/images/image-demo-2.jpg',
  'https://file.iviewui.com/images/image-demo-3.jpg',
  'https://file.iviewui.com/images/image-demo-4.jpg',
  'https://file.iviewui.com/images/image-demo-5.jpg',
  'https://file.iviewui.com/images/image-demo-6.jpg'
]
</script>

Standalone Preview Component

The ImagePreview component can also be used standalone.

<template>
  <div>
    <b-button @click="handleShowPreview">Open Image Preview</b-button>
    <b-image-preview v-model="preview" :preview-list="urlList" />
  </div>
</template>

<script setup>
import { ref } from 'vue'
const urlList = [
  'https://wangbin3162.github.io/bin-files/animals/00.jpg',
  'https://wangbin3162.github.io/bin-files/animals/01.jpg',
  'https://wangbin3162.github.io/bin-files/animals/02.jpg',
  'https://wangbin3162.github.io/bin-files/animals/03.jpg',
  'https://wangbin3162.github.io/bin-files/animals/04.jpg',
  'https://wangbin3162.github.io/bin-files/animals/05.jpg',
  'https://wangbin3162.github.io/bin-files/animals/06.jpg',
  'https://wangbin3162.github.io/bin-files/animals/07.jpg'
]

const preview = ref(false)

function handleShowPreview() {
  preview.value = true
}
</script>

Props

Parameter	Description	Type	Options	Default
src	Image URL	String	—	—
alt	Image description	String	—	—
referrer-policy	Native attribute	String	—	—
width	Width	String / Number	—	—
height	Height	String / Number	—	—
fit	Image fit mode: fill, contain, cover, none, scale-down	String		—
lazy	Enable lazy loading	Boolean	—	false
scroll-container	Scroll container	String , HTMLElement	—	false
append-to-body	Append the overlay to body	Boolean	—	false
mask-closable	Allow clicking the mask to close	Boolean	—	true
preview-tip	Whether to show preview tip and mask	Boolean	—	true
preview	Whether to enable image preview	Boolean	—	false
preview-list	Image preview list	Array	—	[]
infinite	Whether to loop switching	Boolean	—	true
initial-index	Initial index when opening preview	Number	—	0
toolbar	Image preview toolbar options, sorted by array order	Array	—	['zoomIn', 'zoomOut', 'original', 'rotateLeft', 'rotateRight', 'download']
failText	Failure text	String	—	Failed
loadingText	Loading text	String	—	Loading...
previewText	Preview text	String	—	Preview

Events

Event Name	Description	Return Value
load	Image loaded successfully	-
error	Image failed to load	-
switch	Image preview switch	-
close	Image preview closed	Object
click	Image click	initialIndex

Slots

Name	Description
placeholder	Custom image loading placeholder
error	Custom image loading failure
preview	Custom image preview

Image ​

Basic Usage ​

Loading ​

Load Failure ​

Lazy Loading ​

Preview ​

Standalone Preview Component ​

Props ​

Events ​

Slots ​