Images

Images display visual content with support for light/dark mode variants, clickable links, and responsive sizing. They're perfect for showcasing screenshots, diagrams, charts, or any visual content that enhances your documentation. Each image can include a caption and supports multiple display modes.

Properties

src

string required

The primary image source URL. This is the image that will be displayed in light mode or as the fallback.

You may use relative paths if assetsDir is set in your scalar.config.json

activeSrc

string optional

An alternative image source that takes precedence over src. Useful for dynamic image switching or when you need to override the primary source.

src-dark

string optional

A separate image source for dark mode. When provided, this image will be displayed when the user's theme is set to dark mode.

width

number optional

The width of the image in pixels. When specified, the image size will automatically be set to custom.

height

number optional

The height of the image in pixels. When specified, the image size will automatically be set to custom.

alt

string optional

Alternative text for accessibility. This describes the image for screen readers and other assistive technologies.

caption

string optional

A descriptive caption for the image. This appears below the image and provides context or explanation.

href

string optional

A URL that the image links to. When provided, the image becomes clickable and opens the link in a new tab.

size

'actual' | 'custom' | 'full' optional

The display size of the image:

• actual: Shows the image at its natural size
• custom: Uses custom width/height dimensions
• full: Makes the image full width

Defaults to actual.

Examples

Basic Image

<scalar-image src="https://avatars.githubusercontent.com/u/6176314?v=4" alt="Application screenshot"> </scalar-image>

<scalar-image
  src="https://avatars.githubusercontent.com/u/6176314?v=4"
  alt="Application screenshot">
</scalar-image>

::scalar-image{ src="https://avatars.githubusercontent.com/u/6176314?v=4" alt="Application screenshot" }

::scalar-image{ src="https://avatars.githubusercontent.com/u/6176314?v=4" alt="Application screenshot" }

Image with Caption

<scalar-image src="https://avatars.githubusercontent.com/u/6176314?v=4" alt="System architecture diagram" caption="High-level system architecture showing data flow"> </scalar-image>

<scalar-image
  src="https://avatars.githubusercontent.com/u/6176314?v=4"
  alt="System architecture diagram"
  caption="High-level system architecture showing data flow">
</scalar-image>

::scalar-image{ src="https://avatars.githubusercontent.com/u/6176314?v=4" alt="System architecture diagram" caption="High-level system architecture showing data flow" }

::scalar-image{ src="https://avatars.githubusercontent.com/u/6176314?v=4" alt="System architecture diagram" caption="High-level system architecture showing data flow" }

Clickable Image

<scalar-image src="https://avatars.githubusercontent.com/u/301879?s=200&v=4" alt="Click to view full size" href="https://github.com/scalar/scalar" caption="Click to access the link"> </scalar-image>

<scalar-image
  src="https://avatars.githubusercontent.com/u/301879?s=200&v=4"
  alt="Click to view full size"
  href="https://github.com/scalar/scalar"
  caption="Click to access the link">
</scalar-image>

::scalar-image{ src="https://avatars.githubusercontent.com/u/301879?s=200&v=4" alt="Click to view full size" href="https://github.com/scalar/scalar" caption="Click to access the link" }

::scalar-image{ src="https://avatars.githubusercontent.com/u/301879?s=200&v=4" alt="Click to view full size" href="https://github.com/scalar/scalar" caption="Click to access the link" }

Custom Sized Image

<scalar-image src="https://avatars.githubusercontent.com/u/301879?s=200&v=4" alt="Company logo" width="200" height="100" caption="Company branding"> </scalar-image>

<scalar-image
  src="https://avatars.githubusercontent.com/u/301879?s=200&v=4"
  alt="Company logo"
  width="200"
  height="100"
  caption="Company branding">
</scalar-image>

::scalar-image{ src="https://avatars.githubusercontent.com/u/301879?s=200&v=4" alt="Company logo" width="200" height="100" caption="Company branding" }

::scalar-image{ src="https://avatars.githubusercontent.com/u/301879?s=200&v=4" alt="Company logo" width="200" height="100" caption="Company branding" }

Dark Mode Image

<scalar-image src="https://avatars.githubusercontent.com/u/301879?s=200&v=4" src-dark="https://avatars.githubusercontent.com/u/6176314?s=200&v=4" alt="Theme-aware illustration" caption="Automatically adapts to user's theme preference"> </scalar-image>

<scalar-image
  src="https://avatars.githubusercontent.com/u/301879?s=200&v=4"
  src-dark="https://avatars.githubusercontent.com/u/6176314?s=200&v=4"
  alt="Theme-aware illustration"
  caption="Automatically adapts to user's theme preference">
</scalar-image>

::scalar-image{ src="https://avatars.githubusercontent.com/u/301879?s=200&v=4" src-dark="https://avatars.githubusercontent.com/u/6176314?s=200&v=4" alt="Theme-aware illustration" caption="Automatically adapts to user's theme preference" }

::scalar-image{ src="https://avatars.githubusercontent.com/u/301879?s=200&v=4" src-dark="https://avatars.githubusercontent.com/u/6176314?s=200&v=4" alt="Theme-aware illustration" caption="Automatically adapts to user's theme preference" }

Full Width Image

<scalar-image src="https://pbs.twimg.com/profile_banners/1599772885857538051/1740351609/1500x500" alt="Hero section background" size="full" caption="Full-width hero image"> </scalar-image>

<scalar-image
  src="https://pbs.twimg.com/profile_banners/1599772885857538051/1740351609/1500x500"
  alt="Hero section background"
  size="full"
  caption="Full-width hero image">
</scalar-image>

::scalar-image{ src="https://pbs.twimg.com/profile_banners/1599772885857538051/1740351609/1500x500" alt="Hero section background" size="full" caption="Full-width hero image" }

::scalar-image{ src="https://pbs.twimg.com/profile_banners/1599772885857538051/1740351609/1500x500" alt="Hero section background" size="full" caption="Full-width hero image" }

Relative Path Link

<scalar-image src="/hero_1500x500.jpeg" alt="Hero section background" size="full" caption="Relative Path to Full-width hero image"> </scalar-image>

<scalar-image
  src="/hero_1500x500.jpeg"
  alt="Hero section background"
  size="full"
  caption="Relative path Full-width hero image">
</scalar-image>

::scalar-image{ src="/hero_1500x500.jpeg" alt="Hero section background" size="full" caption="Full-width hero image" }

::scalar-image{ src="/hero_1500x500.jpeg" alt="Hero section background" size="full" caption="Full-width hero image" }

<scalar-callout type="info"> The path is relative based on the configured assetsDir. </scalar-callout>

// scalar.config.json
{
  "assetsDir": "documentation/assets"
}