VpvImage Usage

This component provides advanced image handling with support for light/dark mode variations, zoom functionality, responsive sizing, and flexible layout options. It's designed to replace standard markdown images when you need more control and features.

Setup

Do initial installation first

Before you follow any of the guides below, you should import and install this project in your VitePress site.

Import the component in docs/.vitepress/theme/index.ts (or equivalent)

index.ts

import { VpvImage } from '@cynber/vitepress-valence'

export default {
    enhanceApp({ app, router, siteData }) {
    app.component('VpvImage', VpvImage) 
    }
} satisfies Theme

Simple Image

View Code

<VpvImage 
  :imageConfig="{ 
    image: '/demo-blog/june-dark.jpg'
  }" 
/>

Which displays as:

Simple Image + Description

View Code

<VpvImage 
  :imageConfig="{ 
    image: '/demo-blog/june-dark.jpg'
    alt: 'My image',
    description: 'A couple standing by the water at dusk - Credits to Olegs Jonins on Unsplash'
  }" 
/>

Which displays as:

A couple standing by the water at dusk - Credits to Olegs Jonins on Unsplash

Simple Light/Dark Mode Images

View Code

<VpvImage 
  :imageConfig="{ 
    image: '/demo-blog/june-light.jpg',
    image_dark: '/demo-blog/june-dark.jpg'
    alt: 'Five birds flying on the sea - Credits to frank mckenna on Unsplash',
    alt_dark: 'A couple standing by the water at dusk - Credits to Olegs Jonins on Unsplash',
    description: 'Five birds flying on the sea - Credits to frank mckenna on Unsplash',
    description_dark: 'A couple standing by the water at dusk - Credits to Olegs Jonins on Unsplash'
  }" 
/>

Which displays as:

A branch with cherry blossoms - Credits to Redd Francisco on Unsplash

TIP: Try toggling the theme

Press the sun/moon toggle in the top right corner of the site. The images in this demo will also change to reflect the theme.

hideDescription

Hide the image caption (default: false):

View Code

<VpvImage :imageConfig="{image: '/demo-blog/june-dark.jpg'}" hideDescription />

Which displays as:

enableZoom

Enable click-to-zoom with medium-zoom (default: false):

View Code

<VpvImage :imageConfig="{image: '/demo-blog/may-light.jpg'}" enableZoom />

Which displays as:

Click/Tap to Zoom

When zoom is enabled, clicking/tapping on the image will open the image in a larger view.

Zoom Customization

You can adjust what the zoomed-in view looks like by adjusting the margins and background color:

View Code

<VpvImage 
  :imageConfig="{image: '/demo-blog/may-light.jpg'}"
  enableZoom
  :zoomMargin="50"
  zoomBackground="rgba(0, 0, 0, 0.8)"
/>

Which displays as:

Sizing & Layout

Basic Sizing

View Code

<VpvImage 
  :imageConfig="{image: '/demo-blog/may-light.jpg'}"
  width="400px"
  height="300px"
  maxWidth="600px"
/>

Which displays as:

Aspect Ratio

View Code

<VpvImage 
  :imageConfig="{image: '/demo-blog/may-light.jpg'}"
  aspectRatio="16/9"
/>

Which displays as:

Float Positioning

You can float the image to the left or right of the text:

View Code

<!-- Float left with text wrapping -->
<VpvImage 
  :imageConfig="{
    image: '/demo-blog/may-dark.jpg'
  }"
  float="left" 
  width="400px"
  :enableZoom="true"
/>
Empty brown wooden bench - Credits to kychan on Unsplash. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam nec purus nec nunc astutis. Tortor at risus viverra adipiscing at in tellus integer feugiat.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam nec purus nec nunc astutis.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam nec purus nec nunc astutis.

<!-- Float right with text wrapping -->
<VpvImage 
  :imageConfig="{image: '/demo-blog/july-dark.jpg'}"
  float="right" 
  width="400px" 
  :enableZoom="true"
/>

A couple of tents sitting in the middle of a forest - Credits to Fajar Magsyar on Unsplash. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam nec purus nec nunc astutis. Tortor at risus viverra adipiscing at in tellus integer feugiat. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Which displays as:

Empty brown wooden bench - Credits to kychan on Unsplash. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam nec purus nec nunc astutis. Tortor at risus viverra adipiscing at in tellus integer feugiat.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam nec purus nec nunc astutis.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam nec purus nec nunc astutis.

A couple of tents sitting in the middle of a forest - Credits to Fajar Magsyar on Unsplash. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam nec purus nec nunc astutis. Tortor at risus viverra adipiscing at in tellus integer feugiat. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Border & Radius

View Code

<!-- With border -->
<VpvImage :imageConfig="{image: '/demo-blog/october-dark.jpg'}" enableBorder />

<!-- Without rounded corners -->
<VpvImage :imageConfig="{image: '/demo-blog/october-dark.jpg'}" :enableRadius="false" />

Example with border:

Example without rounded corners: