CtrlK
BlogDocsLog inGet started
Tessl Logo

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

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

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@vuepress/plugin-medium-zoom@1.9.x
Publish Source
CLI
Badge
tessl/npm-vuepress--plugin-medium-zoom badge