Overview

#

KImg displays an image and provides functionality to manipulate it such as setting its dimensions, aspect ratio, scaling, letterboxing, and more.

Usage

#

Unless you set fixed dimensions, KImg is responsive by default.

Note that the majority of settings are applied to the image container rather than the image itself. If you need to apply dimensions, aspect ratio, etc. directly to the image, you can use 'fitXY' scale type .

Depending on the scale type and other settings, the image may be letterboxed. When an image is letterboxed, backgroundColor (gray by default) fills the remaining space.

This is in more detail illustrated in the examples below, where the original image dimensions are 200×114 px.

Rendering within inline and block elements

Inline

When rendered within an inline element, the image preserves its original dimensions by default.

      <span>
        <KImg
          src="hummingbird.jpg"
          altText="A sitting hummingbird"
        />
      </span>
    

Block

When rendered within a block element, the image container fills the parent block element and the image scales with the 'centerInside' scale type by default.

      <div>
        <KImg
          src="hummingbird.jpg"
          altText="A sitting hummingbird"
        />
      </div>
    

Dimensions

You can apply the most common dimensions to the image container via props such as width, maxHeight, and others. Values may be either numbers or strings consisting of a numeral and a valid unit. The following units are supported: %, cm, em, ex, ch, in, lh, mm, px, rem, rlh, vh, vw. If you don't provide a unit, px will be used by default.

      <KImg
        src="hummingbird.jpg"
        altText="A sitting hummingbird"
        height="250.2px"
        width="100%"
        maxWidth="10vw"
        :minWidth="25"
      />
    

Alternative text

Unless an image is decorative, you need to provide alternative text via altText.

      <KImg
        src="hummingbird.jpg"
        altText="A sitting hummingbird"
      />
    

If it's meant to be decorative, indicate it by using isDecorative. Alternative text won't be required in this case and the image will be hidden from assistive technologies.

      <KImg
        src="hummingbird.jpg"
        isDecorative
      />
    

Scaling

The scale type determines how an image scales within the image container.

'centerInside' scale type

Scales an image uniformly and maintains its original aspect ratio. Both its width and height are equal to or less than the width and height of the image container. An image can be letterboxed. It's the safest mode as it never distorts an image or impairs its quality.

      <div>
        <KImg
          src="hummingbird.jpg"
          altText="A sitting hummingbird"
          height="200px"
          width="100%"
          maxWidth="500px"
          scaleType="centerInside"
        />
      </div>
    

'contain' scale type

Behaves similarly to 'centerInside' except it ensures that at least one axis of an image fits the image container exactly. The original aspect ratio is maintained. An image can be letterboxed. This mode may impair an image's quality by enlarging it above its original size.

      <div>
        <KImg
          src="hummingbird.jpg"
          altText="A sitting hummingbird"
          height="200px"
          width="100%"
          maxWidth="500px"
          scaleType="contain"
        />
      </div>
    

'fitXY' scale type

Scales X and Y axis of an image independently, so that the image matches the container exactly. An image is never letterboxed. This mode may impair an image's quality by enlarging it above its original size, or distort its aspect ratio.

      <div>
        <KImg
          src="hummingbird.jpg"
          altText="A sitting hummingbird"
          height="200px"
          width="100%"
          maxWidth="500px"
          scaleType="fitXY"
        />
      </div>
    

Aspect ratio

You can set the aspect ratio of the image container with aspectRatio and combine it with any of the scale types.

Note that the ratio styles calculations need to have the width information, therefore it needs to be available in some way. For example, you can set the width directly on KImg. Alternatively, you could ensure that KImg's parent element has width by setting it explicitly or by using a block element.

      <div>
        <KImg
          src="hummingbird.jpg"
          altText="A sitting hummingbird"
          aspectRatio="4:3"
        />
      </div>
    

Placeholder area

The placeholder area is displayed when an image is not available. The area respects the dimensions set on the image container and is gray by default. You can change the area color via backgroundColor and use the #placeholder slot to place content in the area.

      <div>
        <KImg
          src=""
          isDecorative
          aspectRatio="16:9"
          maxWidth="200"
        >
          <template #placeholder>
            <span :style="{ display: 'flex', height: '100%', justifyContent: 'center', alignItems: 'center' }">
              <KIcon icon="readSolid" />
            </span>
          </template>
        </KImg>
      </div>
    

Displaying content on top of an image

Use #topLeft, #topRight, #bottomLeft, or #bottomRight slots to place content on top of the image container.

      <KImg
        src="hummingbird.jpg"
        altText="A sitting hummingbird"
      >
        <template #topLeft>
          <span :style="{ display: 'inline-block', margin: '8px', padding: '2px', backgroundColor: 'white' }">
            Top left
          </span>
        </template>
      </KImg>
    

Top left

Props

#

Events

#

Slots

#