Skip to content

Kirby 3.5.7.1

Image

<k-image>

The k-image component simplifies loading and sizing of images and their backgrounds.

<k-image src="myimage.jpg" />

It can be used as a replacement for regular img tags, but has a bunch of additional options and built-in lazy-loading.

Props

alt

String (default: null)

Just like in regular img tags, you can and should define a proper alt attribute whenever possible.

<k-image src="myimage.jpg" alt="A house with a tree" />

The component will add an empty alt tag when no alt text is specified to be skipped by screen readers. Otherwise the filename would be read.

caption

String (default: null)

An additional caption below the image

back

String (default: null)

By default the background of images will be transparent. But you can change it to black, white or pattern

<k-image back="black" src="myimage.jpg" />
<k-image back="pattern" src="myimage.jpg" />
<k-image back="white" src="myimage.jpg" />

ratio

String (default: null)

The container can be set to a fixed ratio. The ratio can be defined freely with the format widthFraction/heightFraction. The ratio will be calculated automatically. Here are some examples.

Square

  • 1/1

Landscape

  • 2/1
  • 3/1
  • 3/2
  • 4/3
  • 16/9

Portrait

  • 2/3
  • 3/4
  • 4/5
<k-image ratio="1/1" src="myimage.jpg" />
<k-image ratio="3/2" src="myimage.jpg" />

cover

Boolean (default: false)

If images don't fit the defined ratio, the component will add additional space around images. You can change that behavior with the cover attribute. If true, the image will be cropped to fit the ratio.

<k-image ratio="1/1" src="myimage.jpg" :cover="true" />

Events

You can bind any native event to the image. Additionally the image component will fire a load or error event, once the image has been loaded or failed to load.

<k-image
  ratio="1/1"
  src="myimage.jpg"
  :crop="true"
  @load="yayLoaded"
  @error="ohNo"
  @click="clicked"
/>

CSS class

.k-image