or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-vuepress--plugin-medium-zoom

A VuePress plugin that integrates medium-zoom library to provide image zoom functionality for documentation sites.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@vuepress/plugin-medium-zoom@1.9.x

To install, run

npx @tessl/cli install tessl/npm-vuepress--plugin-medium-zoom@1.9.0

index.mddocs/

VuePress Medium Zoom Plugin

A VuePress plugin that integrates the medium-zoom library to provide elegant image zoom functionality for documentation sites. The plugin enables users to click on images to expand them with a smooth zoom animation overlay, enhancing the visual experience of documentation without additional UI complexity.

Package Information

  • Package Name: @vuepress/plugin-medium-zoom
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install @vuepress/plugin-medium-zoom

Core Imports

VuePress plugins are typically imported and configured in the VuePress configuration file:

// .vuepress/config.js
module.exports = {
  plugins: [
    ['@vuepress/plugin-medium-zoom', options]
  ]
}

For programmatic usage:

const mediumZoomPlugin = require('@vuepress/plugin-medium-zoom');

Basic Usage

Default Configuration

Enable the plugin with default settings that target content images not wrapped in links:

// .vuepress/config.js
module.exports = {
  plugins: [
    '@vuepress/plugin-medium-zoom'
  ]
}

Custom Selector Configuration

Configure the plugin to target specific images using CSS selectors:

// .vuepress/config.js
module.exports = {
  plugins: [
    ['@vuepress/plugin-medium-zoom', {
      selector: '.my-custom-images img',
      options: {
        margin: 16,
        background: 'rgba(25, 18, 25, 0.9)',
        scrollOffset: 40
      }
    }]
  ]
}

Capabilities

Plugin Factory Function

Creates a VuePress plugin configuration object with medium-zoom integration.

/**
 * VuePress plugin factory function for medium-zoom integration (default export)
 * @param {PluginOptions} options - Plugin configuration options
 * @param {VuePressContext} context - VuePress application context
 * @returns {VuePressPlugin} Plugin configuration object
 */
module.exports = (options, context) => VuePressPlugin;

interface PluginOptions {
  /** CSS selector for images to apply zoom functionality */
  selector?: string;
  /** Configuration options passed to medium-zoom library */
  options?: MediumZoomOptions;
}

interface VuePressPlugin {
  /** Global constants injected into client-side code */
  define: {
    SELECTOR: string;
    OPTIONS: MediumZoomOptions | undefined;
  };
  /** Path to client-side Vue.js mixin */
  clientRootMixin: string;
}

Plugin Configuration Options

Configure image targeting and zoom behavior through the options parameter.

interface PluginOptions {
  /**
   * CSS selector for images to apply zoom functionality
   * @default '.theme-default-content :not(a) > img'
   */
  selector?: string;
  
  /**
   * Configuration options passed directly to medium-zoom library
   * Supports all medium-zoom configuration options
   */
  options?: MediumZoomOptions;
}

interface MediumZoomOptions {
  /** Spacing around the zoomed image in pixels */
  margin?: number;
  /** Background color/style for the zoom overlay */
  background?: string;
  /** Vertical offset from viewport top when scrolling */
  scrollOffset?: number;
  /** Additional medium-zoom configuration options */
  [key: string]: any;
}

Client-Side Integration

The plugin automatically injects a Vue.js mixin that handles zoom initialization and lifecycle management.

interface ClientRootMixin {
  /** Vue component data containing zoom instance */
  data(): {
    zoom: MediumZoomInstance | null;
  };
  
  /** Initialize zoom functionality when component mounts */
  mounted(): void;
  
  /** Reinitialize zoom when component updates (SPA navigation) */
  updated(): void;
  
  /** Update/reinitialize zoom functionality with current DOM state */
  methods: {
    updateZoom(): void;
  };
}

interface MediumZoomInstance {
  /** Remove zoom functionality from all images */
  detach(): void;
  /** Additional medium-zoom instance methods */
  [key: string]: any;
}

CSS Styling

The plugin includes CSS styling for proper z-index management of zoom overlays.

/* Zoom overlay container styling */
.medium-zoom-overlay {
  z-index: 100;
}

/* Zoomed image styling - ensures image appears above overlay */
.medium-zoom-overlay ~ img {
  z-index: 101;
}

Configuration Examples

Target All Images

module.exports = {
  plugins: [
    ['@vuepress/plugin-medium-zoom', {
      selector: 'img'
    }]
  ]
}

Target Images in Specific Container

module.exports = {
  plugins: [
    ['@vuepress/plugin-medium-zoom', {
      selector: '.content-wrapper img:not([data-no-zoom])'
    }]
  ]
}

Advanced Medium-Zoom Configuration

module.exports = {
  plugins: [
    ['@vuepress/plugin-medium-zoom', {
      selector: '.theme-default-content :not(a) > img',
      options: {
        margin: 24,
        background: 'rgba(0, 0, 0, 0.8)',
        scrollOffset: 0,
        container: {
          top: 24,
          right: 24,
          bottom: 24,
          left: 24
        },
        template: {
          closeButton: true
        }
      }
    }]
  ]
}

Integration Details

VuePress Integration Points

  • Plugin System: Uses VuePress plugin architecture with factory function pattern
  • Global Constants: Injects SELECTOR and OPTIONS globally via define mechanism
  • Client Mixin: Provides Vue.js component mixin for lifecycle management
  • Theme Compatibility: Default selector targets VuePress default theme structure
  • SPA Support: Handles Vue.js component updates and navigation changes

Medium-Zoom Library Integration

  • Dependency: Uses medium-zoom@^1.0.4 as core zoom functionality
  • Configuration Passthrough: All medium-zoom options supported via options parameter
  • Instance Management: Handles proper initialization, cleanup, and DOM updates
  • Lifecycle Integration: Manages zoom instance lifecycle with Vue.js component lifecycle

Browser Compatibility

  • Modern Browsers: Full support for modern browsers with ES6+ features
  • CSS Requirements: Requires CSS support for z-index and transitions
  • Touch Support: Inherits touch/mobile support from medium-zoom library

Default Behavior

  • Default Selector: .theme-default-content :not(a) > img - targets content images not wrapped in links
  • Lazy Initialization: 1-second delay before zoom initialization to ensure DOM stability
  • Automatic Cleanup: Detaches previous zoom instances before reinitializing
  • SPA Navigation: Automatically reinitializes zoom when Vue.js components update