feat: smart image preloading with build-time extraction and runtime scheduling

Extract image URLs at parse time from all sources (frontmatter, markdown,
Vue component props, CSS url()) and store in `images[]` on SlideInfoBase.
This field survives build-mode content stripping.

Build-time: generates `<link rel="preload" as="image">` tags in HTML head.
Runtime: navigation-aware composable preloads current + ahead window
immediately, then all remaining slides after 3s.

Configurable via headmatter `preloadImages` (default: true).
Supersedes slidevjs#2450 with comprehensive coverage.

Author: troshab

packages/client/composables/usePreloadImages.ts

@@ -0,0 +1,83 @@
+import type { SlideRoute } from '@slidev/types'
+import type { ComputedRef, Ref } from 'vue'
+import configs from '#slidev/configs'
+import { watchEffect } from 'vue'
+
+const loaded = new Set<string>()
+const loading = new Set<string>()
+
+function resolveUrl(url: string): string {
+  if (url.startsWith('http') || url.startsWith('//'))
+    return url
+  const base = (import.meta.env.BASE_URL || '/').replace(/\/$/, '')
+  return `${base}${url.startsWith('/') ? url : `/${url}`}`
+}
+
+function preloadImage(url: string): void {
+  const resolved = resolveUrl(url)
+  if (loaded.has(resolved) || loading.has(resolved))
+    return
+  loading.add(resolved)
+  const img = new Image()
+  img.onload = () => {
+    loading.delete(resolved)
+    loaded.add(resolved)
+  }
+  img.onerror = () => {
+    loading.delete(resolved)
+  }
+  img.src = resolved
+}
+
+function preloadSlideImages(route: SlideRoute): void {
+  const images = route.meta?.slide?.images
+  if (images?.length) {
+    for (const url of images)
+      preloadImage(url)
+  }
+}
+
+export function usePreloadImages(
+  currentRoute: ComputedRef<SlideRoute>,
+  prevRoute: ComputedRef<SlideRoute>,
+  nextRoute: ComputedRef<SlideRoute>,
+  slides: Ref<SlideRoute[]>,
+): void {
+  const config = configs.preloadImages
+  if (config === false)
+    return
+
+  const ahead = (typeof config === 'object' && config?.ahead) || 3
+
+  // Preload current + prev + next + look-ahead window
+  watchEffect(() => {
+    const current = currentRoute.value
+    const all = slides.value
+    if (!current || !all?.length)
+      return
+
+    preloadSlideImages(current)
+    preloadSlideImages(prevRoute.value)
+    preloadSlideImages(nextRoute.value)
+
+    // Preload ahead window
+    const currentIdx = current.no - 1
+    for (let i = 1; i <= ahead; i++) {
+      const idx = currentIdx + i
+      if (idx < all.length)
+        preloadSlideImages(all[idx])
+    }
+  })
+
+  // Preload all remaining slides after 3s
+  watchEffect((onCleanup) => {
+    const all = slides.value
+    const timeout = setTimeout(() => {
+      if (all?.length) {
+        for (const route of all)
+          preloadSlideImages(route)
+      }
+    }, 3000)
+    onCleanup(() => clearTimeout(timeout))
+  })
+}

packages/client/constants.ts

@@ -87,4 +87,5 @@ export const HEADMATTER_FIELDS = [
   'seoMeta',
   'notesAutoRuby',
   'magicMoveDuration',
+  'preloadImages',
 ]

packages/client/internals/SlidesShow.vue

@@ -5,6 +5,7 @@ import { recomputeAllPoppers } from 'floating-vue'
 import { computed, shallowRef, TransitionGroup, watchEffect } from 'vue'
 import { createFixedClicks } from '../composables/useClicks'
 import { useNav } from '../composables/useNav'
+import { usePreloadImages } from '../composables/usePreloadImages'
 import { useViewTransition } from '../composables/useViewTransition'
 import { CLICKS_MAX } from '../constants'
 import { activeDragElement, disableTransition, hmrSkipTransition } from '../state'
@@ -49,6 +50,9 @@ watchEffect((onCleanup) => {
   onCleanup(() => clearTimeout(timeout))
 })
 
+// preload images for nearby slides
+usePreloadImages(currentSlideRoute, prevRoute, nextRoute, slides)
+
 const hasViewTransition = useViewTransition()
 
 const DrawingLayer = shallowRef<any>()

packages/parser/src/config.ts

@@ -51,6 +51,7 @@ export function getDefaultConfig(): SlidevConfig {
     duration: '30min',
     timer: 'stopwatch',
     magicMoveDuration: 800,
+    preloadImages: true,
   }
 }
 

packages/parser/src/core.ts

@@ -66,6 +66,60 @@ function matter(code: string, options: SlidevParserOptions) {
   }
 }
 
+const IMAGE_EXTENSIONS = /\.(?:png|jpe?g|gif|svg|webp|avif|ico|bmp|tiff?)$/i
+
+/**
+ * Extract image URLs from slide content and frontmatter.
+ * Strips code blocks first to avoid false positives.
+ */
+export function extractImages(content: string, frontmatter: Record<string, any>): string[] {
+  const images = new Set<string>()
+
+  // Collect from frontmatter keys
+  for (const key of ['image', 'backgroundImage', 'background']) {
+    const val = frontmatter[key]
+    if (typeof val === 'string' && val && !val.startsWith('data:')) {
+      // For `background`, only include if it looks like an image URL
+      if (key === 'background') {
+        if (IMAGE_EXTENSIONS.test(val) || val.startsWith('/') || val.startsWith('http'))
+          images.add(val)
+      }
+      else {
+        images.add(val)
+      }
+    }
+  }
+
+  // Strip code blocks to avoid false positives
+  const stripped = content.replace(/^```[\s\S]+?^```/gm, '')
+
+  // Markdown images: ![alt](url)
+  for (const [, url] of stripped.matchAll(/!\[[^\]]*\]\(([^)]+)\)/g)) {
+    if (url && !url.startsWith('data:'))
+      images.add(url.trim())
+  }
+
+  // Vue component props: src="url", image="url"
+  for (const [, url] of stripped.matchAll(/\b(?:src|image)=["']([^"']+)["']/g)) {
+    if (url && !url.startsWith('data:') && !url.includes('{{') && IMAGE_EXTENSIONS.test(url))
+      images.add(url.trim())
+  }
+
+  // Vue bound props: :src="'/path/to/img.png'"
+  for (const [, url] of stripped.matchAll(/:(?:src|image)=["']'([^']+)'["']/g)) {
+    if (url && !url.startsWith('data:') && IMAGE_EXTENSIONS.test(url))
+      images.add(url.trim())
+  }
+
+  // CSS url() with image extension filter
+  for (const [, url] of stripped.matchAll(/url\(["']?([^"')]+)["']?\)/g)) {
+    if (url && !url.startsWith('data:') && IMAGE_EXTENSIONS.test(url))
+      images.add(url.trim())
+  }
+
+  return Array.from(images)
+}
+
 export function detectFeatures(code: string): SlidevDetectedFeatures {
   return {
     katex: !!code.match(/\$.*?\$/) || !!code.match(/\$\$/),
@@ -104,6 +158,8 @@ export function parseSlide(raw: string, options: SlidevParserOptions = {}): Omit
   if (frontmatter.level)
     level = frontmatter.level || 1
 
+  const images = extractImages(content, frontmatter)
+
   return {
     raw,
     title,
@@ -116,6 +172,7 @@ export function parseSlide(raw: string, options: SlidevParserOptions = {}): Omit
     frontmatterDoc: matterResult.doc,
     frontmatterRaw: matterResult.raw,
     note,
+    images,
   }
 }
 

packages/slidev/node/setups/indexHtml.ts

@@ -16,6 +16,33 @@ function toAttrValue(unsafe: unknown) {
   return JSON.stringify(escapeHtml(String(unsafe)))
 }
 
+function collectPreloadImages(data: Omit<ResolvedSlidevOptions, 'utils'>['data'], base?: string): ResolvableLink[] {
+  const config = data.config
+  if (config.preloadImages === false)
+    return []
+
+  const seen = new Set<string>()
+  const links: ResolvableLink[] = []
+  const basePrefix = base ? base.replace(/\/$/, '') : ''
+
+  for (const slide of data.slides) {
+    const images = slide.images || slide.source?.images
+    if (!images?.length)
+      continue
+    for (const url of images) {
+      if (seen.has(url))
+        continue
+      seen.add(url)
+      const href = url.startsWith('http') || url.startsWith('//')
+        ? url
+        : `${basePrefix}${url.startsWith('/') ? url : `/${url}`}`
+      links.push({ rel: 'preload', as: 'image', href })
+    }
+  }
+
+  return links
+}
+
 export default async function setupIndexHtml({ mode, entry, clientRoot, userRoot, roots, data, base }: Omit<ResolvedSlidevOptions, 'utils'>): Promise<string> {
   let main = await readFile(join(clientRoot, 'index.html'), 'utf-8')
   let body = ''
@@ -75,6 +102,7 @@ export default async function setupIndexHtml({ mode, entry, clientRoot, userRoot
         link: [
           data.config.favicon ? { rel: 'icon', href: data.config.favicon } : null,
           ...webFontsLink,
+          ...collectPreloadImages(data, base),
         ].filter(x => x),
         meta: [
           { 'http-equiv': 'Content-Type', 'content': 'text/html; charset=UTF-8' },

packages/types/src/frontmatter.ts

@@ -311,6 +311,16 @@ export interface HeadmatterConfig extends TransitionOptions {
    * @default 800
    */
   magicMoveDuration?: number
+  /**
+   * Preload images extracted from slides for faster navigation.
+   *
+   * - `true` - enable with default look-ahead of 3 slides
+   * - `false` - disable image preloading
+   * - `{ ahead: number }` - enable with custom look-ahead window
+   *
+   * @default true
+   */
+  preloadImages?: boolean | { ahead?: number }
 }
 
 export interface Frontmatter extends TransitionOptions {

packages/types/src/types.ts

@@ -13,6 +13,11 @@ export interface SlideInfoBase {
   note?: string
   title?: string
   level?: number
+  /**
+   * Image URLs extracted from the slide content (frontmatter, markdown, Vue components, CSS).
+   * Populated at parse time to survive build-mode content stripping.
+   */
+  images?: string[]
 }
 
 export interface SourceSlideInfo extends SlideInfoBase {

packages/vscode/schema/headmatter.json

@@ -551,6 +551,24 @@
           "markdownDescription": "Duration for shiki magic move transitions in milliseconds",
           "default": 800
         },
+        "preloadImages": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "object",
+              "properties": {
+                "ahead": {
+                  "type": "number"
+                }
+              }
+            }
+          ],
+          "description": "Preload images extracted from slides for faster navigation.\n\n- `true` - enable with default look-ahead of 3 slides\n- `false` - disable image preloading\n- `{ ahead: number }` - enable with custom look-ahead window",
+          "markdownDescription": "Preload images extracted from slides for faster navigation.\n\n- `true` - enable with default look-ahead of 3 slides\n- `false` - disable image preloading\n- `{ ahead: number }` - enable with custom look-ahead window",
+          "default": true
+        },
         "defaults": {
           "$ref": "#/definitions/Frontmatter",
           "description": "Default frontmatter options applied to all slides",