Vue ImageKit SDK

The Vue ImageKit SDK is a Vue-specific wrapper built on top of the core ImageKit JavaScript SDK. It brings ImageKit’s URL generation, transformation, responsive-image handling, and file-upload capabilities to Vue 3 in a lightweight package with full TypeScript support.

Source code is available on GitHub under the MIT license.

The SDK works in both SSR (e.g. Nuxt 3) and CSR (Vite / Vue CLI).

Install the SDK via npm, yarn, or pnpm:

npm i @imagekit/vue
# or
yarn add @imagekit/vue
# or
pnpm add @imagekit/vue

What's included in the SDK:

<script setup lang="ts">
import { Image } from '@imagekit/vue'
</script>

<template>
  <Image
    url-endpoint="https://ik.imagekit.io/your_imagekit_id"
    src="/profile.png"
    width="500"
    height="500"
    alt="Author photo" />
</template>

To avoid repeating urlEndpoint everywhere, you can wrap your components in an ImageKitProvider component. All nested Image and Video components will inherit the urlEndpoint and transformationPosition props from the provider.

Any children will be rendered as-is, so you can use it to wrap your entire app or just a part of it.

<script setup lang="ts">
import { ImageKitProvider, Image } from '@imagekit/vue'
</script>

<template>
  <ImageKitProvider url-endpoint="https://ik.imagekit.io/your_imagekit_id">
    <Image
      src="/profile.png"
      width="500"
      height="500"
      alt="Author photo" />
  </ImageKitProvider>
</template>

The Image component is a wrapper around the HTML img element. It allows you to use ImageKit’s URL generation and transformation, lazy-loading, responsive images etc.

It accepts every regular <img> attribute plus the following ImageKit-specific props. All other attributes (class, id, data-, aria-, etc.) are forwarded untouched except srcset. The SDK will generate the srcset attribute automatically and ignore any custom srcset you provide.

The Video component is a lightweight wrapper around the HTML video element. It allows you to use ImageKit’s URL generation and transformation capabilities. It supports all HTML video attributes and additionally accepts the following ImageKit-specific props - urlEndpoint, transformation, transformationPosition, and queryParameters. For the definition of these props, refer to the Image component section.

<Video
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/movie.mp4"
  controls
  width="640"
  height="360" />

With ImageKit, you can resize images on the fly using the width and height properties. The SDK automatically generates the appropriate URL with the specified dimensions.

<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/photo.jpg"
  width="300"
  height="300"
  :transformation="[{ width: 300, height: 300 }]"
  alt="Square thumb" />

The <Image> component in Vue SDK comes with built-in support for responsive images, enabled by default. It automatically generates the appropriate srcset attributes ensuring images are delivered in the most optimal dimension for various screen sizes.

Behind the scenes, it utilizes the getResponsiveImageAttributes helper from the core JavaScript SDK to compute these responsive attributes.

To disable responsive behavior, simply set the responsive prop to false. This will prevent the component from generating the srcset attributes automatically.

The Image component supports lazy loading by default. You can control this behavior using the loading prop.

By default, loading is set to lazy, which defers loading the image until it is near the viewport.

If set to eager, the image loads immediately.

<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/photo.jpg"
  width="300"
  height="300"
  loading="eager"
  alt="Eager load" />

To lazy load a video using Video component, you can set the preload attribute to none and specify a poster image by extracting a thumbnail from the video.

The buildSrc utility function is used to generate the thumbnail URL. It accepts the same parameters as the Video/Image component and returns a URL with the specified transformations.

Refer to the create thumbnail documentation for detailed instructions on generating a thumbnail from a video using ImageKit.

<script setup lang="ts">
import { Video, buildSrc } from '@imagekit/vue'

const posterUrl = buildSrc({
  urlEndpoint: 'https://ik.imagekit.io/your_imagekit_id',
  src: '/movie.mp4/ik-thumbnail.jpg'
})
</script>

<template>
  <Video
    url-endpoint="https://ik.imagekit.io/your_imagekit_id"
    src="/movie.mp4"
    preload="none"
    controls
    :poster="posterUrl" />
</template>

You can chain multiple transformations together by passing an array of transformation objects. Each object can specify different properties, such as width, height, cropping, overlays, and effects. See chained transformations for more details.

<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/profile.png"
  :transformation="[
    { width: 400, height: 300 },
    { rotation: 90 }
  ]"
  width="400"
  height="300"
  alt="Rotated" />

You can add overlays to images and videos. The overlay can be a text, image, video, or subtitle.

Besides the overlay type, you can also specify the position, size, and other properties of the overlay. Check the overlay options for more details.

<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/background.png"
  :transformation="[
    { overlay: { type: 'image', input: 'logo.png' } }
  ]"
  width="400"
  height="300"
  alt="Background with image overlay" />

You can independently transform the overlay image by passing a transformation array inside the overlay object. The transformation will be applied to the overlay image only.

<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/background.png"
  :transformation="[
    { 
      overlay: { 
        type: 'image',
        input: 'logo.png',
        transformation: [{ width: 100, height: 100 }]
      } 
    }
  ]"
  width="400"
  height="300"
  alt="Background with image overlay" />

Image overlays support a wide range of transformations. Check reference for the complete list of transformations supported on image overlays.

You can add a solid color overlay to images and videos.

<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/background.jpg"
  width="400"
  height="300"
  :transformation="[
    { 
      overlay: { 
        type: 'solidColor', 
        color: 'FF0000',
      } 
    }
  ]" />

You can also specify the width, height, and other properties of the solid color overlay. For example:

<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/background.jpg"
  width="400"
  height="300"
  :transformation="[
    { 
      overlay: { 
        type: 'solidColor', 
        color: 'FF0000',
        transformation: [
          { width: 100, height: 100 }
        ]
      } 
    }
  ]" />

For more options related to styling the solid color overlay, check the solid color overlay transformations section.

You can add text overlays to images and videos.

<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/background.jpg"
  width="400"
  height="300"
  :transformation="[
    { 
      overlay: { 
        type: 'text', 
        text: 'Hello World',
      } 
    }
  ]" />

You can also specify the font size, color, and other properties of the text overlay. For example:

<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/background.jpg"
  width="400"
  height="300"
  :transformation="[
    { 
      overlay: { 
        type: 'text', 
        text: "Hello, ImageKit!",
        transformation: [
          { fontSize: 20, fontColor: 'FF0000' }
        ] 
      } 
    }
  ]" />

Check the text overlay transformations section for more options related to styling the text.

You can add video overlays on videos only.

<Video
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/background.mp4"
  controls
  :transformation="[
    { 
      overlay: { 
        type: 'video', 
        input: 'overlay.mp4',
      } 
    }
  ]" />

Additionally, you can specify the start and duration for the overlay video. For example:

<Video
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/background.mp4"
  controls
  :transformation="[
    { 
      overlay: { 
        type: 'video', 
        input: 'overlay.mp4',
        timing: { start: 5, duration: 10 }
      } 
    }
  ]" />

You can also independently transform the overlay video. For example, to resize the overlay video:

<Video
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/background.mp4"
  controls
  :transformation="[
    { 
      overlay: { 
        type: 'video', 
        input: 'overlay.mp4',
        transformation: [{ width: 100, height: 100 }]
      } 
    }
  ]" />

All supported video transformations can also be applied to overlay videos.

If you're overlaying an image on a base video, refer to this list for all the transformations supported on image overlays.

You can add subtitle overlays on videos.

<Video
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/background.mp4"
  controls
  :transformation="[
    { 
      overlay: { 
        type: 'subtitle', 
        input: 'subtitle.srt',
      } 
    }
  ]" />

The subtitle overlay can be styled with various properties such as font size, color, and outline. See the Subtitle Overlay Transformations section for all styling options.

<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/photo.jpg"
  alt="Photo with background removal"
  width="400"
  height="300"
  :transformation="[
    { aiRemoveBackground: true }
  ]" />

ImageKit supports multiple AI-powered transformations, like upscaling, generative fill, and more More examples:

<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/photo.jpg"
  alt="Photo with AI drop shadow"
  width="400"
  height="300"
  :transformation="[
    { aiDropShadow: true }
  ]" />

Upscaling example:

<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/photo.jpg"
  alt="Photo with AI upscaling"
  width="400"
  height="300"
  :transformation="[
    { aiUpscale: true }
  ]" />

You can use arithmetic expressions to dynamically compute transformation values. For example, to set the width to half of the original image width:

<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/photo.jpg"
  alt="Photo with arithmetic width"
  width="400"
  height="300"
  :transformation="[
    { width: "iw_div_2" }
  ]" />

Check out the Arithmetic Expressions reference for more examples and details.

The Vue.js SDK exports a utility function, .upload, which enables you to upload files to ImageKit. This upload() function leverages the Upload V1 API, accepting an options object and returning a promise that resolves with the upload response.

The SDK automatically converts certain parameters into JSON strings, as required by the API. If a parameter is not explicitly supported by the SDK, it is included in the request as-is. For a complete list of parameters and expected formats, refer to the API documentation.

The upload() function accepts a JSON object with the following parameters:

The .upload function expects the following mandatory parameters:

• file and fileName – The file to be uploaded and the name you want to assign to it. The file value can be a File object, a base64-encoded string, or a URL.
• Authentication parameters – token, signature, expire, and publicKey.

Authentication is essential for secure file uploads from the browser. You should never expose your private API key in client-side code. Instead, generate these one-time authentication parameters on the server side and pass them to the client.

To simplify the process, all of our backend SDKs include utility functions for generating authentication parameters.

Here’s how the upload process using the SDK works:

1. Client Request for Auth Parameters
   The client component calls an API route to fetch the authentication parameters.
   You can implement your own application logic within this route to authenticate the user.
   After that, use one of our backend SDKs to generate the required auth parameters and return them to the client.

2. File Upload
   Once the client has the auth parameters, it can call the .upload function with the necessary data.

The following example demonstrates how to create an API route that generates authentication parameters using the ImageKit Node.js SDK.

You can find your private key and public key in the ImageKit dashboard.

const express = require('express');
const app = express();
const ImageKit = require('imagekit'); // Node.js SDK

const imagekit = new ImageKit({
  urlEndpoint: '<YOUR_IMAGEKIT_URL_ENDPOINT>', // https://ik.imagekit.io/your_imagekit_id
  publicKey: process.env.IMAGEKIT_PUBLIC_KEY,
  privateKey: process.env.IMAGEKIT_PRIVATE_KEY
});

// allow cross-origin requests
app.use(function(req, res, next) {
  res.header("Access-Control-Allow-Origin", "*");
  res.header("Access-Control-Allow-Headers", 
    "Origin, X-Requested-With, Content-Type, Accept");
  next();
});

app.get('/auth', function (req, res) {
  // Your application logic to authenticate the user
  // For example, you can check if the user is logged in or has the necessary permissions
  // If the user is not authenticated, you can return an error response
  const { token, expire, signature } = imagekit.getAuthenticationParameters();
  res.send({ token, expire, signature, publicKey: process.env.IMAGEKIT_PUBLIC_KEY });
});

app.listen(3000, function () {
  console.log('Live at Port 3000');
});

Now your client-side code can call this API route to retrieve the upload parameters.

The example below demonstrates how to use the .upload function in a client component to upload a file, including error handling for various upload scenarios. You can copy and paste this code into your client component and customize it as needed.

<script setup lang="ts">
import {
  upload,
  ImageKitAbortError,
  ImageKitInvalidRequestError,
  ImageKitUploadNetworkError,
  ImageKitServerError
} from '@imagekit/vue'
import { ref } from 'vue'

const progress = ref(0)
const fileInput = ref<HTMLInputElement>()

const aborter = new AbortController()

async function authenticate() {
  const res = await fetch('/api/auth')
  if (!res.ok) throw new Error(await res.text())
  return (await res.json()) as {
    signature: string; expire: number; token: string; publicKey: string
  }
}

async function handleUpload() {
  const file = fileInput.value?.files?.[0]
  if (!file) return alert('Choose a file')

  let creds
  try { creds = await authenticate() } catch (e) {
    return console.error('Auth failed', e)
  }

  try {
    const resp = await upload({
      ...creds,
      file,
      fileName: file.name,
      onProgress: e => (progress.value = e.loaded / e.total * 100),
      abortSignal: aborter.signal
    })
    console.log('Upload OK', resp)
  } catch (err) {
    if (err instanceof ImageKitAbortError)        console.warn('Aborted')
    else if (err instanceof ImageKitInvalidRequestError) console.error('Bad request')
    else if (err instanceof ImageKitUploadNetworkError)  console.error('Network')
    else if (err instanceof ImageKitServerError)         console.error('Server side')
    else console.error(err)
  }
}
</script>

<template>
  <input type="file" ref="fileInput" />
  <button @click="handleUpload">Upload</button>
  <progress :value="progress" max="100" />
</template>

The SDK assigns a name to each transformation parameter (e.g., height maps to h, width maps to w). If the property does not match any of the following supported options, it is added as is in the URL.

If you want to generate transformations without any modifications, use the raw parameter. For example, SDK doesn't provide a nice way to write conditional transformations, so you can use the raw parameter to add them as is.

Check transformation documentation for complete reference on all transformations supported by ImageKit.

If you specify a transformation parameter that is not explicitly supported by the SDK, it is added “as-is” in the generated URL. This provides flexibility for using new or custom transformations without waiting for an SDK update. However add @ts-ignore to avoid TypeScript errors for unsupported transformations, or add transformation as a string in the raw parameter.

For example:

buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/photo.jpg",
  transformation: [
    { unsupportedTransformation: "value" }
  ]
});
// Output: https://ik.imagekit.io/your_imagekit_id/photo.jpg?tr=unsupportedTransformation-value

This SDK provides overlay as a transformation parameter. The overlay can be a text, image, video, subtitle, or solid color.

Overlays in ImageKit are applied using layers, allowing you to stack multiple overlays on top of each other. Each overlay can be styled and positioned independently. For more details, refer to the layer documentation.

The SDK automatically generates the correct layer syntax for image, video, text, subtitle, and solid color overlays. You can also specify the overlay position, size, and other properties.

The table below outlines the available overlay configuration options:

Overlay encoding options define how the overlay input is converted for URL construction. When set to auto, the SDK automatically determines whether to use plain text or Base64 encoding based on the input content.

For text overlays:

• If auto is used, the SDK checks the text overlay input: if it is URL-safe, it uses the format i-{input} (plain text); otherwise, it applies Base64 encoding with the format ie-{base64_encoded_input}.
• You can force a specific method by setting encoding to plain (always use i-{input}) or base64 (always use ie-{base64}).
• Note: In all cases, the text is percent-encoded to ensure URL safety.

For image, video, and subtitle overlays:

• The input path is processed by removing any leading/trailing slashes and replacing inner slashes with @@ when plain is used.
• Similarly, if auto is used, the SDK determines whether to apply plain text or Base64 encoding based on the characters present.
• For explicit behavior, use plain or base64 to enforce the desired encoding.

Use auto for most cases to let the SDK optimize encoding, and use plain or base64 when a specific encoding method is required.