Docs
Image
Last modified on June 10, 2025 • 7 min read • 1,322 wordsUse the image shortcode to display a responsive image with a specific aspect ratio.
Overview
Use the image
shortcode to display a responsive image with a specific aspect ratio. The source link can refer to either an image available in the /assets/img
folder of your site or a public web location. The shortcode renders the image as a so-called
Image Set
to optimize the image for different screen sizes and resolutions. Behind the scenes, Hugo renders the images in WebP
format and stores them in a local folder (resources
or public
). The images are processed using the quality setting specified in the [imaging]
section of the main
Config File
(defaults to 75). Supported image types are .png
, .jpeg
, .gif
, .tiff
, .bmp
, and .webp
. A fallback image of type .jpeg
is provided for older browsers.
As an example, the following shortcode displays an image with its original aspect ratio. The image is adjusted for the active color mode. The shortcode processes two images behind the scenes, being img/responsive-light.png
and img/responsive-dark.png
. Only the image that matches the current color mode is shown.


{{< image src="img/responsive.png" mode="true" caption="Image caption" >}}
Arguments
The shortcode supports the following arguments:
Name | Type | Required | Default | Comment |
---|---|---|---|---|
anchor | select |
v0.24.22
Anchor of the image’s crop box, defaults to anchor value set in imaging section of the site configuration (usually Smart ). Supported values: [TopLeft , Top , TopRight , Left , Center , Right , BottomLeft , Bottom , BottomRight , Smart ]. |
||
caption | string | Caption of the carousel slide or illustration. | ||
class | string | Class attributes of the element. It supports Bootstrap attributes to modify the styling of the element. | ||
figclass | string |
v0.23.0
Class attribute of the figure caption, e.g. px-4 . |
||
image-height | int | v1.0.0 Height of the image in pixels. | ||
image-width | int | v1.0.0 Width of the image in pixels. | ||
loading | select | eager |
v0.21.0
Image loading behavior. The loading of lazily loaded images is deferred until the image is within scrolling range of the viewport. This should reduce the initial loading time of the website. It is recommended to lazily load only those images that are below the page fold. Supported values: [lazy , eager ]. |
|
mode | bool | Flag indicating if the media asset should support color modes. If set, the elements searches for images having a matching color-mode suffix such as -light or -dark . |
||
plain | bool | v0.24.0 Flag to indicate if the image should render a plain image instead of an image set. When set, no transformations are applied to the image. | ||
portrait | bool | v0.18.3 Flag to adjust the image ratio from landscape to portrait. The image itself is not rotated, only the crop area is adjusted. Not applicable to vector graphics. | ||
ratio | select | Ratio of the media asset. When the asset is an image, it is resized and cropped (not applicable to vector graphics). For video assets, the padding of the embedded frame is adjusted. When set to auto, the original aspect ratio is used. Supported values: [1x1 , 3x2 , 4x3 , 16x9 , 21x9 , auto ]. |
||
src | string | Path or url of the image, e.g. img/example.jpg . Images with multiple color modes are expected to have a basename that ends with either -dark or -light . |
||
title | string, hstring.RenderedString, hstring.HTML, template.HTML | Title of the element. If the element references a (local) page, the title overrides the referenced page’s title. | ||
url | string, template.URL |
v1.0.0
Use src instead. Path or url of the image, e.g. img/example.jpg . Images with multiple color modes are expected to have a basename that ends with either -dark or -light . |
||
wrapper | string |
v0.18.3
Class attribute of the element’s wrapper. It supports Bootstrap attributes to modify the styling of the element. Icons include the fa-wrapper and fa-fluid attributes by default. |
Name | Type | Required | Default |
---|---|---|---|
anchor | select | ||
v0.24.22
Anchor of the image’s crop box, defaults to anchor value set in imaging section of the site configuration (usually Smart ). Supported values: [TopLeft , Top , TopRight , Left , Center , Right , BottomLeft , Bottom , BottomRight , Smart ]. |
|||
caption | string | ||
Caption of the carousel slide or illustration. | |||
class | string | ||
Class attributes of the element. It supports Bootstrap attributes to modify the styling of the element. | |||
figclass | string | ||
v0.23.0
Class attribute of the figure caption, e.g. px-4 . |
|||
image-height | int | ||
v1.0.0 Height of the image in pixels. | |||
image-width | int | ||
v1.0.0 Width of the image in pixels. | |||
loading | select | eager |
|
v0.21.0
Image loading behavior. The loading of lazily loaded images is deferred until the image is within scrolling range of the viewport. This should reduce the initial loading time of the website. It is recommended to lazily load only those images that are below the page fold. Supported values: [lazy , eager ]. |
|||
mode | bool | ||
Flag indicating if the media asset should support color modes. If set, the elements searches for images having a matching color-mode suffix such as -light or -dark . |
|||
plain | bool | ||
v0.24.0 Flag to indicate if the image should render a plain image instead of an image set. When set, no transformations are applied to the image. | |||
portrait | bool | ||
v0.18.3 Flag to adjust the image ratio from landscape to portrait. The image itself is not rotated, only the crop area is adjusted. Not applicable to vector graphics. | |||
ratio | select | ||
Ratio of the media asset. When the asset is an image, it is resized and cropped (not applicable to vector graphics). For video assets, the padding of the embedded frame is adjusted. When set to auto, the original aspect ratio is used. Supported values: [1x1 , 3x2 , 4x3 , 16x9 , 21x9 , auto ]. |
|||
src | string | ||
Path or url of the image, e.g. img/example.jpg . Images with multiple color modes are expected to have a basename that ends with either -dark or -light . |
|||
title | string, hstring.RenderedString, hstring.HTML, template.HTML | ||
Title of the element. If the element references a (local) page, the title overrides the referenced page’s title. | |||
url | string, template.URL | ||
v1.0.0
Use src instead. Path or url of the image, e.g. img/example.jpg . Images with multiple color modes are expected to have a basename that ends with either -dark or -light . |
|||
wrapper | string | ||
v0.18.3
Class attribute of the element’s wrapper. It supports Bootstrap attributes to modify the styling of the element. Icons include the fa-wrapper and fa-fluid attributes by default. |
Examples
Change the style of your card with class attributes and shortcode arguments.
Aspect Ratio
As an example, the following shortcodes display a centered image with various aspect ratios.
Set the ratio
to 1x1
for a square aspect ratio.

{{< image src="img/flowers.jpg" ratio="1x1" wrapper="col-6 mx-auto" >}}
Set the ratio
to 3x2
for a landscape aspect ratio.

{{< image src="img/flowers.jpg" ratio="3x2" wrapper="col-6 mx-auto" >}}
Set the ratio
to 4x3
for a landscape aspect ratio.

{{< image src="img/flowers.jpg" ratio="4x3" wrapper="col-6 mx-auto" >}}
Set the ratio
to 16x9
for a landscape aspect ratio.

{{< image src="img/flowers.jpg" ratio="16x9" wrapper="col-6 mx-auto" >}}
Set the ratio
to 21x9
for a landscape aspect ratio.

{{< image src="img/flowers.jpg" ratio="21x9" wrapper="col-6 mx-auto" >}}
Omit the ratio
to keep the original aspect ratio.

{{< image src="img/flowers.jpg" wrapper="col-6 mx-auto" >}}
Color Mode
Set mode
to true
to use an image that is color-mode aware. The shortcode processes two images behind the scenes, being img/responsive-light.png
and img/responsive-dark.png
. Only the image that matches the current color mode is shown.


{{< image src="img/responsive.png" mode="true" >}}
Figures
Add a caption
to transform the image into a figure with caption.

{{< image src="img/watch.jpg" caption="Figure caption" >}}
Vector Images
The shortcode supports vector images of type .svg
too. The shortcode supports the regular arguments, however, vector images are contained instead of cropped when the ratio
is set. The next example shows a color-mode-aware vector image. The background is set to a contrasting color to illustrate the ratio behavior.
Important
Since release v0.26.3 , vector images stored in the site’s
assets
folder are embedded as inline vector images. Vector images stored in thestatic
folder are kept as separate files.
{{< image src="/img/logo_var.svg#logo" class="img-fluid w-50" wrapper="text-center" >}}