Image

Display images with lazy loading, fit modes, and fallbacks.

Basic Usage

<template>
  <bp-image
    width="300px"
    height="200px"
    src="https://cos.birdpaper.design/birdpaper-ui/v2/image-demo/img_1.jpg?imageMogr2/thumbnail/!80p"
    alt="Sample image"
  />
</template>

Fit Mode

fit maps to CSS object-fit: fill, contain, cover, none, scale-down.

fill

contain

cover

none

scale-down

<template>
  <div class="demo-area">
    <div class="fit-item" v-for="fit in fitTypes" :key="fit">
      <p>{{ fit }}</p>
      <bp-image
        width="80px"
        height="80px"
        :fit
        src="https://cos.birdpaper.design/birdpaper-ui/v2/image-demo/img_1.jpg?imageMogr2/thumbnail/!80p"
      />
    </div>
  </div>
</template>

<script setup lang="ts">
const fitTypes = ["fill", "contain", "cover", "none", "scale-down"];
</script>

<style lang="scss" scoped>
.demo-area {
  display: flex;
  gap: 16px;
  .fit-item {
    display: flex;
    flex-direction: column;
    align-items: center;
    gap: 8px;

    p {
      color: #8c8c8c;
      font-size: 13px;
    }
  }
}
</style>

Fallback

Handle load failures with fallback or the error slot.

<template>
  <bp-space :size="16">
    <bp-image
      width="200px"
      height="150px"
      src="https://invalid-url/broken.jpg"
      fallback="https://cos.birdpaper.design/birdpaper-ui/v2/image-demo/img_1.jpg?imageMogr2/thumbnail/!80p"
    />
    <bp-image width="200px" height="150px" src="https://invalid-url/broken.jpg">
      <template #error>
        <div class="error-slot">
          <IconCloseCircleLine size="28" />
          <span>Load failed</span>
        </div>
      </template>
    </bp-image>
  </bp-space>
</template>

<script setup lang="ts">
import { IconCloseCircleLine } from "birdpaper-icon";
</script>

<style lang="scss" scoped>
.error-slot {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  height: 100%;
  color: #c9cdd4;
  gap: 4px;

  span {
    font-size: 12px;
  }
}
</style>

Load Effect

load-effect supports fade, blur, and none.

fade

blur

none

<template>
  <div class="demo-area">
    <div class="effect-item">
      <p>fade</p>
      <bp-image
        width="200px"
        height="140px"
        src="https://cos.birdpaper.design/birdpaper-ui/v2/image-demo/img_1.jpg?imageMogr2/thumbnail/!80p"
        load-effect="fade"
      />
    </div>
    <div class="effect-item">
      <p>blur</p>
      <bp-image
        width="200px"
        height="140px"
        src="https://cos.birdpaper.design/birdpaper-ui/v2/image-demo/img_1.jpg?imageMogr2/thumbnail/!80p"
        load-effect="blur"
      />
    </div>
    <div class="effect-item">
      <p>none</p>
      <bp-image
        width="200px"
        height="140px"
        src="https://cos.birdpaper.design/birdpaper-ui/v2/image-demo/img_1.jpg?imageMogr2/thumbnail/!80p"
        load-effect="none"
      />
    </div>
  </div>
</template>

<style lang="scss" scoped>
.demo-area {
  display: flex;
  gap: 16px;

  .effect-item {
    display: flex;
    flex-direction: column;
    align-items: center;
    gap: 8px;

    p {
      color: #8c8c8c;
      font-size: 13px;
    }
  }
}
</style>

Image Props

src	Image source URL	String	-	-
alt	Alt text	String	-	-
title	Image title	String	-	-
width	Image width (CSS units supported)	String	-	-
height	Image height (CSS units supported)	String	-	-
fit	Object-fit mode (same as CSS object-fit)	String	fill	-
fallback	Fallback image URL on error	String	-	-
lazy	Whether to enable lazy loading	Boolean	-	-
placeholder	Placeholder image URL for lazy loading	String	-	-
load-effect	Load animation effect	String	fade	-

Image Events

load	Triggered when the image finishes loading	ev: Event	-
error	Triggered when the image fails to load	ev: Event	-

Image Slots

loading	Placeholder while loading	-	-
error	Content shown on load error	-	-