Vue

<!-- ix-docs-ignore -->

@imgix/vue is a client library for generating URLs with imgix.

Vue 3

You are viewing the Vue 3.0 branch. For Vue 2, please look at the 2.x branch. We will be supporting Vue 2 for the official support timeline (18 months) after we release Vue 3 support.

<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->

<!-- ALL-CONTRIBUTORS-BADGE:END -->

---

<!-- /ix-docs-ignore --> <!-- NB: Run `npx markdown-toc README.md --maxdepth 4 | sed -e 's/[[:space:]]\{2\}/ /g'` to generate TOC :) --> <!-- prettier-ignore-start -->

• Overview / Resources
• Get Started
• Configure
  • Polyfills required
  • Standard Vue 3.x App
  • Nuxt.js
• Usage
  • Examples
    • Basic Use Case
    • Flexible Image Rendering
    • Fixed Image Rendering (i.e. non-flexible)
    • Picture Support
    • Lazy-Loading
      • Lazy-loading (Native)
      • Lazy-loading (Event Listener)
  • Advanced Examples
    • buildUrlObject
    • buildUrl
    • buildSrcSet
    • Custom Attribute Mapping
    • Custom Srcset Width
    • Width Tolerance
    • Minimum and Maximum Width Ranges
    • Base64 Encoding
• What Is the ixlib Param on Every Request?
• Code of Conduct
• Contributors
• License

<!-- prettier-ignore-end -->

Overview / Resources

Before you get started with @imgix/vue, it's highly recommended that you read Eric Portis' seminal article on srcset and sizes. This article explains the history of responsive images in responsive design, why they're necessary, and how all these technologies work together to save bandwidth and provide a better experience for users. The primary goal of @imgix/vue is to make these tools easier for developers to implement, so having an understanding of how they work will significantly improve your @imgix/vue experience.

Below are some other articles that help explain responsive imagery, and how it can work alongside imgix:

• Using imgix with <picture>. Discusses the differences between art direction and resolution switching, and provides examples of how to accomplish art direction with imgix.
• Responsive Images with srcset and imgix. A look into how imgix can work with srcset and sizes to serve the right image.

Get Started

Firstly, follow this quick start guide to set-up an imgix account.

Then, install @imgix/vue with the following commands, depending on your package manager.

• NPM: npm install @imgix/vue
• Yarn: yarn add @imgix/vue

This module exports two transpiled versions. If a ES6-module-aware bundler is being used to consume this module, it will pick up an ES6 module version and can perform tree-shaking. If you are not using ES6 modules, you don't have to do anything.

Configure

Polyfills required

A polyfill for Object.assign must be supplied for browsers that need it. You probably have this already set up, so you likely don't need to do anything.

Standard Vue 3 App

For Vue 2, please look at the main branch.

@imgix/vue needs to be initialized with a minimal configuration before it can be used in components. Modify your startup/init file (usually main.js or similar) to include the following:

import { createApp } from 'vue';
import VueImgix from '@imgix/vue';
import App from './App.vue';

// Create and mount the root instance.
const app = createApp(App);
// Make sure to _use_ the VueImgix instance to make the
// whole app VueImgix-aware.
app.use(VueImgix, {
  domain: "<your company's imgix domain>",
  defaultIxParams: {
    // This enables the auto format imgix parameter by default for all images, which we recommend to reduce image size, but you might choose to turn this off.
    auto: 'format',
  },
});

app.mount('#app');

And that's all you need to get started! Have fun!

Nuxt.js v3

With nuxt-image

Nuxt.js now has a built-in Image component that can be used alongside imgix.

You can read more about our nuxt-image provider and how to use it in the Nuxt docs.

Using this library directly

For Nuxt v2 support, please look at the main branch.

To use this library with Nuxt 3, add the following code to plugins/vue-imgix.js

import { defineNuxtPlugin } from '#app';
import VueImgix from '@imgix/vue';

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(VueImgix, {
    domain: "<your company's imgix domain>",
    defaultIxParams: {
      // This enables the auto format imgix parameter by default for all images, which we recommend to reduce image size, but you might choose to turn this off.
      auto: 'format',
    },
  });
});

Example usage

<nuxt-img
  provider="imgix"
  src="/blog/woman-hat.jpg"
  width="300"
  height="500"
  fit="cover"
  :modifiers="{ auto: 'format,compress', crop: 'faces' }"
/>

Usage

To help you get started as quickly as possible, imgix has designed the API of this library to follow the API of a normal <img> tag as much as possible. You can expect most uses of the <img> tag to work just the same for <ix-img>.

Examples

Basic Use Case

To render a simple image that will display an image based on the browser's DPR and the width of the rendered element using the power of srcsets, @imgix/vue can be used as follows:

<ix-img src="examples/pione.jpg" sizes="100vw" />

To render an image with a source URL different than the one setup in the plugin configuration, just set the src attribute to the absolute URL path of the image, like so:

<ix-img src="https://sdk-test.imgix.net/amsterdam.jpg" sizes="100vw" />

Please note: 100vw is an appropriate sizes value for a full-bleed image. If your image is not full-bleed, you should use a different value for sizes. Eric Portis' "Srcset and sizes" article goes into depth on how to use the sizes attribute. An important note here is that sizes cannot be a percentage based value, and must be in terms of vw, or a fixed size (px, em, rem, etc)

This will generate HTML similar to the following:

<img
  src="https://assets.imgix.net/examples/pione.jpg?auto=format"
  sizes="100vw"
  srcset="
    https://assets.imgix.net/examples/pione.jpg?auto=format&w=100 100w,
    https://assets.imgix.net/examples/pione.jpg?auto=format&w=200 200w,
    ...
  "
/>

Flexible Image Rendering

This component acts dynamically by default. The component will leverage srcset and sizes to render the right size image for its container. This is an example of this responsive behaviour.

sizes should be set properly for this to work well, and some styling should be used to set the size of the component rendered. Without sizes and correct styling the image might render at full-size.

✨There is new browser behavior in 2019/2020. It is now recommended that width and height be set on all images to provide an aspect ratio hint to the browser. The browser can then use this aspect ratio hint to reserve a space for the image (even if the image is responsive!). The following example explains all how to do it. You can also read more about this development in this amazing Smashing Magazine article.

For the width/height placeholder image, we need three requirements to be met:

• width and height attributes set on the img element
• some width CSS value (e.g. 10px, 100%, calc(100vw - 10px))
• height: auto as a CSS property

./styles.css

.test-img {
  /* These next two lines are critical for the new browser feature. */
  width: calc(100vw - 128px);
  height: auto; // This tells the browser to set the height of the image to what it should be, and ignore the height attribute set on the image
}

./app.js

For the width and height attributes, they can be any value as long as their aspect ratio is the same as what the image's