Customization

Zoomed images are displayed in a modal <dialog> element which includes a backdrop displayed behind the image.

Customizing the backdrop

By default, the backdrop background color is an non-transparent color based on Starlight’s color palette. You can customize this color using the --starlight-image-zoom-backdrop-bg CSS custom property.

To learn how to add custom CSS styles to Starlight, refer to the “Custom CSS styles” guide in the Starlight documentation.

:root {
  /* Custom backdrop background color in dark mode. */
  --starlight-image-zoom-backdrop-bg: oklch(0 0 0);
}

:root[data-theme='light'] {
  /* Custom backdrop background color in light mode. */
  --starlight-image-zoom-backdrop-bg: oklch(100% 0 0);
}

Customizing zoomed images using IDs

When zooming images, the id attribute of the image is not copied to the zoomed image in the modal. If you are using the id attribute to identify images and customize their appearance using CSS, you can use the data-zoom-id attribute which will contain the id of the original image.

For example, if your page includes Mermaid diagrams with IDs like mermaid-1, mermaid-2, etc., the following CSS snippet inverts the color samples of all the diagrams in dark mode:

:root[data-theme='dark'] img[id^='mermaid-'] {
  filter: invert(1);
}

To apply the same effect to the zoomed images, you can use the data-zoom-id attribute in your CSS selector:

:root[data-theme='dark'] img[id^='mermaid-'],
:root[data-theme='dark'] img[data-zoom-id^='mermaid-'] {
  filter: invert(1);
}