Skip to content
Starlight Image Zoom

Getting Started

A Starlight plugin adding zoom capabilities to your documentation images.

  • Lightweight UI based on the <dialog> element
  • No client-side third-party dependencies
  • Markdown and MDX images support: Markdown syntax, HTML syntax, and the <Image> or <Picture> components
  • Alternate text displayed as a caption
  • Accessible buttons to trigger zoom

Check out the demo for a preview of the plugin in action.

Prerequisites

You will need to have a Starlight website set up. If you don’t have one yet, you can follow the “Getting Started” guide in the Starlight docs to create one.

Installation

  1. Starlight Image Zoom is a Starlight plugin that you can install using your favorite package manager:

    Terminal window
    npm i starlight-image-zoom

  2. Configure the plugin in your Starlight configuration in the astro.config.mjs file.

    astro.config.mjs
    import starlight from '@astrojs/starlight'
    import { defineConfig } from 'astro/config'
    import starlightImageZoom from 'starlight-image-zoom'
    

    export default defineConfig({
      integrations: [
        starlight({
          plugins: [starlightImageZoom()],
          title: 'My Docs',
        }),
      ],
    })

  3. Start the development server to see the plugin in action.

The Starlight Image Zoom plugin behavior can be tweaked using various configuration options.

Component overrides

The Starlight Image Zoom plugin uses a Starlight component override for the MarkdownContent component to add zoom capabilities to images.

If you have a custom MarkdownContent component override in your Starlight project, you will need to manually render the ImageZoom component from the Starlight Image Zoom plugin in your custom component:

src/components/overrides/MarkdownContent.astro
---
import type { Props } from '@astrojs/starlight/props'
import Default from '@astrojs/starlight/components/MarkdownContent.astro'
import ImageZoom from 'starlight-image-zoom/components/ImageZoom.astro'
---


<ImageZoom />
<p>Custom content in the MarkdownContent override</p>
<Default {...Astro.props}><slot /></Default>