Image

Lazy loading responsive images

The Buefy Logo
A random image
<template>
    <section>
        <div class="block">
            <b-field grouped group-multiline>
                <div class="control">
                    <b-switch v-model="rounded"> Rounded </b-switch>
                </div>
            </b-field>
        </div>

        <b-image
            :src="require('@/assets/buefy.png')"
            alt="The Buefy Logo"
            ratio="601by235"
            :rounded="rounded"
        ></b-image>
        <b-image
            src="https://picsum.photos/600/400"
            alt="A random image"
            ratio="6by4"
            :rounded="rounded"
        ></b-image>
    </section>
</template>

<script>
    export default {
        data() {
            return {
                rounded: false,
            }
        }
    }
</script>

# webp

You can use the new webp format for your image. Do not forget to set a fallback for browsers that do not supports this format yet.

If you specify only an extension as a fallback, only the extension will be replaced. It is useful if your image is at the same location and have the same filename. You can also specify a full URL as a fallback.

You will see the same pictures twice in browsers that do support webp format. The second image will be different in browsers that do not support it.

Source loaded: https://picsum.photos/id/237/800/450.webp


Source loaded: https://picsum.photos/id/237/800/450.webp

<template>
    <section>
        <p>Source loaded: {{loadedSrc1}}</p>
        <b-image
            src="https://picsum.photos/id/237/800/450.webp"
            webp-fallback=".jpg"
            ratio="16by9"
            @load="onLoad1"
        ></b-image>
        <br>
        <p>Source loaded: {{loadedSrc2}}</p>
        <b-image
            src="https://picsum.photos/id/237/800/450.webp"
            webp-fallback="https://picsum.photos/id/1025/800/450.jpg"
            ratio="16by9"
            @load="onLoad2"
        ></b-image>
    </section>
</template>

<script>
    export default {
        data() {
            return {
                loadedSrc1: '',
                loadedSrc2: '',
            }
        },
        methods: {
            onLoad1(event, src) {
                this.loadedSrc1 = src
            },
            onLoad2(event, src) {
                this.loadedSrc2 = src
            }
        }
    }
</script>

# Placeholder

You can use a placeholder image that will be loaded at start and will be displayed until the src gets loaded. You can reload the page to see what is happening.

In the first example, you will see a blurred Buefy logo appear upon src is loaded.
In the second example, you will see the lqip effect while a smaller blurred version of the image upon src is loaded.
In the third example, you will see Buefy skeleton appear upon src is loaded.



<template>
    <section>
        <b-image
            src="https://picsum.photos/id/1074/800/400"
            placeholder="/static/img/icons/favicon-32x32.png"
            ratio="2by1"
        ></b-image>
        <br>
        <b-image
            src="https://picsum.photos/id/237/800/400"
            placeholder="https://picsum.photos/id/237/200/100?blur=10"
            ratio="2by1"
        ></b-image>
        <br>
        <b-image
            src="https://picsum.photos/id/1062/800/400"
            ratio="2by1"
        >
            <b-skeleton
                class="skeleton-placeholder"
                slot="placeholder"
                height="100%"
            ></b-skeleton>
        </b-image>
    </section>
</template>

<style scoped>
/deep/ .b-skeleton {
    height: 100%;
    position: absolute;
    top: 0;
}
</style>

# srcset

You can use srcset attribute or the srcsetSizes prop to generate one for you.

When using srcsetSizes, it will generate a string like "`${srcFilename}-${size}.${srcExt} ${size}w`" for each sizes. You can control this format using the srcsetFormatter prop

Source loaded:


Source loaded: https://picsum.photos/id/1074/800/400

<template>
    <section>
        <p>Source loaded: {{loadedSrc1}}</p>
        <b-image
            src="https://picsum.photos/id/1062/1600/900"
            srcset="https://picsum.photos/id/1062/400/225 400w, https://picsum.photos/id/1062/800/450 800w, https://picsum.photos/id/1062/1600/900 1600w"
            ratio="16by9"
            @load="onLoad1"
        ></b-image>
        <br>
        <p>Source loaded: {{loadedSrc2}}</p>
        <b-image
            src="https://picsum.photos/id/1074/1600/800"
            :srcset-sizes="[400, 800, 1600]"
            :srcset-formatter="this.formatSrcset"
            ratio="16by8"
            @load="onLoad2"
        ></b-image>
    </section>
</template>

<script>
    export default {
        data() {
            return {
                loadedSrc1: '',
                loadedSrc2: '',
            }
        },
        methods: {
            onLoad1(event, src) {
                this.loadedSrc1 = src
            },
            onLoad2(event, src) {
                this.loadedSrc2 = src
            },
            formatSrcset(src, size) {
                return `https://picsum.photos/id/1074/${size}/${size / 2}`
            }
        }
    }
</script>

# Fallback on error

You can use alt to display an alternative text if the src fails to load.

You can also use src-fallback to display another image if the original fails to load.

A problematic image

Events:[]
<template>
    <section>
        <b-image
            src="https://picsum.photos/id/error/600/400"
            alt="A problematic image"
            ratio="6by4"
            @load="onLoad"
            @error="onError"
        ></b-image>
        <br>
        <b-image
            src="https://picsum.photos/id/error/600/400"
            src-fallback="https://picsum.photos/id/237/600/400"
            ratio="6by4"
            @load="onLoad"
            @error="onError"
        ></b-image>
        <pre style="max-height: 400px"><b>Events:</b>{{ events }}</pre>
    </section>
</template>

<script>
    export default {
        data() {
            return {
                events: [],
            }
        },
        methods: {
            onLoad(event, src) {
                this.events.push(`${src} loaded`)
            },
            onError(event, src) {
                this.events.push(`${src} fails to load`)
            }
        }
    }
</script>

# API

Name
Description
Type
Values
Default
srcThe image url you want to display. You can use webp extension here. Do not forget to specify a fallback for browsers that do not support this format yet.String
altThe image alternate text, if it cannot be displayed.String
src-fallbackThe image url you want to display if the image specified using src fails to load.String
webp-fallbackFallback when using webp format. You can specify an extension only (.jpg, .jpeg, .png, .gif) if the filename is the same. You can use a full url if not.String
lazyUse IntersectionObserver to display the image only when in viewport.Booleantrue
responsiveThe image will take 100% of the parent width. Use this with ratio to prevent page jump when images are loading.Booleantrue
ratioThe space will be reserved. Prevent page jump when images are loading when using responsive.String1by1, 5by4, 4by3, 3by2, 5by3, 16by9, 2by1, 3by1, 4by5, 3by4, 2by3, 3by5, 9by16, 1by2 1by3 or any string having this format {number}by{number}
placeholderThe image that will be displayed before the src load. Useful if you want to use lqip technique. Will use webp-fallback if only an extension is given.String
srcsetYou can enter a valid srcset value (ex. "image1.webp 400w,image2.webp 800w"). Will use webp-fallback if only an extension is given.String
srcset-sizesIt will generate a srcset string using those sizes.Array
srcset-formatterFunction to format src according to a given size.Function(src, size) => `${srcFilename}-${size}.${srcExt}`
roundedRounded image.Booleanfalse

# Variables

You can use these variables to customize this component.

Name
Default
$image-placeholder-blur-enabledtrue
$image-placeholder-blur10px
Bulma variablesLink

This page is open source. Noticed a typo or something's unclear?

Improve this page on GitHub