API Reference

Runtime types

All public types are exported from the package root:

import type {
  ImageStatus, // 'idle' | 'loading' | 'loaded' | 'error'
  SrcSet, // { avif?: string; webp?: string; fallback: string }
  ResponsiveSrc, // Record<string, string | SrcSet> — breakpoint-key → URL, or a format set for that breakpoint
  BreakpointMap, // Record<string, string> — breakpoint-key → CSS media query
  VImageKitOptions, // { breakpoints?: BreakpointMap; serverRoute?: string }
  LazyImgOptions, // { src, placeholder?, rootMargin?, threshold?, onLoad?, onError? }
  ObjectFit, // 'cover' | 'contain' | 'fill' | 'none' | 'scale-down'
  FocalPoint, // { x: number; y: number } — fractions 0–1
  Densities, // number[] | Record<number, string> — density descriptors
  ImageMeta, // CLI manifest entry / `?vik` import shape, for the `image` prop
  Layout, // 'fixed' | 'responsive' | 'fill' — the `layout` prop
} from '@macrulez/vue-image-kit'

ImageStatus

type ImageStatus = 'idle' | 'loading' | 'loaded' | 'error'

The state machine transitions in order: idle → loading → loaded or idle → loading → error. Drives useImage()'s status ref.

SrcSet

interface SrcSet {
  avif?: string // Optional AVIF source URL
  webp?: string // Optional WebP source URL
  fallback: string // Required — used as the <img src> fallback
}

The shape VImage's src prop takes for WebP/AVIF format switching.

VImageKitOptions

interface VImageKitOptions {
  breakpoints?: BreakpointMap
  serverRoute?: string
}

Options for app.use(VImageKitPlugin, options). breakpoints seeds the global art-direction breakpoints (see Global breakpoints); serverRoute sets the default route for loader="server" (see useServerRoute()).

LazyImgOptions

interface LazyImgOptions {
  src: string
  placeholder?: string
  rootMargin?: string
  threshold?: number
  onLoad?: () => void
  onError?: (e: Event) => void
}

The v-lazy-img directive accepts either a plain string (the src) or a LazyImgOptions object.

Working with typed options in v-lazy-img

import type { LazyImgOptions } from '@macrulez/vue-image-kit'

const bgOptions: LazyImgOptions = {
  src: '/hero.jpg',
  placeholder: 'data:image/jpeg;base64,...',
  rootMargin: '100px',
  onLoad: () => analytics.track('hero_loaded'),
}

<div v-lazy-img="bgOptions" class="hero" />

ObjectFit

type ObjectFit = 'cover' | 'contain' | 'fill' | 'none' | 'scale-down'

VImage's fit prop — passed straight through as the object-fit CSS value.

FocalPoint

interface FocalPoint {
  x: number // 0–1
  y: number // 0–1
}

VImage's focal prop — see Focal point.

Densities

type Densities = number[] | Record<number, string>

VImage's densities prop — see Density descriptors.

ImageMeta

The shape of a CLI manifest entry / ?vik build-time import — everything VImage's image prop can seed at once (src/width/height/blurhash/thumbhash/placeholder/sizes, plus per-width src{width} shortcuts). See Build-time imports.

Layout

type Layout = 'fixed' | 'responsive' | 'fill'

VImage's layout prop — see Layout presets.

Utilities

Pure, dependency-free functions exported from the package root — most already have a dedicated page; this is a flat index.

• generateSrcset(src, widths), generateSizes(sizes?), generateDensitySrcset(src, densities), buildSizes(map, breakpoints) — see srcset + sizes.
• generatePreloadLink(href, options) — see Preload links.
• decodeBlurhash(hash, width, height), decodeThumbHash(hash), thumbHashToAverageRGBA(hash), thumbHashToAverageColor(hash), encodeBlurhash(source, options?), encodeThumbHash(source, options?) — see Placeholders.
• isSaveDataEnabled() — see Network-aware loading.
• buildImageUrl(src, options) — see Self-hosted on-demand server.
• pickSmallestSrcsetUrl(srcset) → string | undefined. Parses a srcset string and returns the URL with the smallest w descriptor. Not documented elsewhere — this is its only mention. Used internally by VImage's respectSaveData prop to downgrade to the cheapest available candidate on a save-data connection (see Network-aware loading); exposed directly for a custom save-data downgrade path outside VImage.