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.
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.
darkModeSrc
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 sizecustom: Uses custom width/height dimensionsfull: 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" }
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" }
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" }
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" }
Dark Mode Image
<scalar-image
src="https://avatars.githubusercontent.com/u/301879?s=200&v=4"
darkModeSrc="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" darkModeSrc="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" }