diff --git a/docs/assets/hummingbird CC BY-SA 4.0.jpg b/docs/assets/hummingbird CC BY-SA 4.0.jpg
new file mode 100644
index 000000000..967146ca4
Binary files /dev/null and b/docs/assets/hummingbird CC BY-SA 4.0.jpg differ
diff --git a/docs/assets/img_sample_for_kimg.png b/docs/assets/img_sample_for_kimg.png
deleted file mode 100644
index f06c72c46..000000000
Binary files a/docs/assets/img_sample_for_kimg.png and /dev/null differ
diff --git a/docs/common/DocsShow.vue b/docs/common/DocsShow.vue
index cd1a8acec..97d9b29ae 100644
--- a/docs/common/DocsShow.vue
+++ b/docs/common/DocsShow.vue
@@ -29,6 +29,20 @@
         type: Boolean,
         required: false,
       },
+      /**
+       * Container width
+       */
+      width: {
+        type: String,
+        required: false,
+      },
+      /**
+       * Container max width
+       */
+      maxWidth: {
+        type: String,
+        required: false,
+      },
     },
     computed: {
       style() {
@@ -36,6 +50,8 @@
           display: this.block ? 'block' : 'inline-block',
           padding: this.padding ? '8px 24px' : null,
           backgroundColor: this.dark ? this.$themePalette.grey.v_500 : undefined,
+          width: this.width ? this.width : undefined,
+          maxWidth: this.maxWidth ? this.maxWidth : undefined,
         };
       },
     },
diff --git a/docs/pages/kimg.vue b/docs/pages/kimg.vue
index 9e738f74f..79e1c8238 100644
--- a/docs/pages/kimg.vue
+++ b/docs/pages/kimg.vue
@@ -2,6 +2,213 @@
 
   <DocsPageTemplate apiDocs>
     <DocsPageSection title="Overview" anchor="#overview">
+      <p>
+        It displays an image and provides additional functionality to manipulate it such as setting dimensions, aspect ratio, scaling, letterboxing, and more.
+      </p>
+    </DocsPageSection>
+
+    <DocsPageSection title="Usage" anchor="#usage">
+      <p>Note that when setting dimensions of the image in any of the supported ways, the settings is applied to its container rather than the image itself. Depending on the scale type and other settings, the image may be letterboxed. If you need to apply dimensions directly to the image, you can use fitXY scale type. This, and other modes are illustrated in the examples below, where the original image dimensions is 200px wide and 114px heigh.</p>
+
+      <p>Unless you set fixed dimensions, <code>KImg</code> is responsive by default.</p>
+
+      <h3>Rendering within inline and block elements</h3>
+
+      <h4>Inline</h4>
+
+      <p>When rendered within an inline element, the image will preserve its original dimensions.</p>
+
+      <DocsShowCode language="html">
+        <span>
+          <KImg
+            src="hummingbird.jpg"
+            altText="A sitting hummingbird"
+          />
+        </span>
+      </DocsShowCode>
+      <DocsShow>
+        <span>
+          <KImg
+            :src="require('../assets/hummingbird CC BY-SA 4.0.jpg')"
+            altText="A sitting hummingbird"
+          />
+        </span>
+      </DocsShow>
+
+
+      <h4>Block</h4>
+
+      <p>When rendered within a block element, by default the image scales to its parent element with the <code>'centerInside'</code> scale type (see below).</p>
+
+      <DocsShowCode language="html">
+        <div>
+          <KImg
+            src="hummingbird.jpg"
+            altText="A sitting hummingbird"
+          />
+        </div>
+      </DocsShowCode>
+      <DocsShow block>
+        <div>
+          <KImg
+            :src="require('../assets/hummingbird CC BY-SA 4.0.jpg')"
+            altText="A sitting hummingbird"
+          />
+        </div>
+      </DocsShow>
+
+      <h3>Dimensions</h3>
+
+      <p>You can set the most common dimensions right on the <code>KImg</code> via props like <code>width</code>, <code>maxHeight</code>, etc. See <a href="#props">Props</a> for a full list. Values may be either numbers or strings consisting of a numeral and valid units.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.</p>
+
+      <DocsShowCode language="html">
+        <div>
+          <KImg
+            src="hummingbird.jpg"
+            altText="A sitting hummingbird"
+            height="250.2px"
+            width="100%"
+            maxWidth="10vw"
+            :minWidth="25"
+          />
+        </div>
+      </DocsShowCode>
+
+      <h3>Alternative text</h3>
+
+      <p>Alternative text (<code>altText</code>) is required by default. If an image <DocsExternalLink text="is decorative" href="https://www.w3.org/WAI/tutorials/images/decorative/" />, then set <code>isDecorative</code> to truthy value. Then, alternative text won't be required and the image will be hidden from assistive technologies.</p>
+
+      <DocsShowCode language="html">
+        <div>
+          <KImg
+            src="hummingbird.jpg"
+            isDecorative
+          />
+        </div>
+      </DocsShowCode>
+
+      <h3>Scaling</h3>
+
+      <h4><code style="font-weight: bold">'centerInside'</code> scale type</h4>
+
+      <p>Scales the image uniformly and maintains its original aspect ratio so that both its width and height are equal to or less than the container.</p>
+
+      <p>The original aspect ratio is maintained. The image can be letterboxed. It's the safest mode as it never distorts the image.</p>
+
+      <DocsShowCode language="html">
+        <div>
+          <KImg
+            src="hummingbird.jpg"
+            altText="A sitting hummingbird"
+            height="200"
+            width="100%"
+            maxWidth="500"
+            scaleType="centerInside"
+          />
+        </div>
+      </DocsShowCode>
+      <DocsShow block>
+        <div>
+          <KImg
+            :src="require('../assets/hummingbird CC BY-SA 4.0.jpg')"
+            altText="A sitting hummingbird"
+            height="200"
+            width="100%"
+            maxWidth="500"
+            scaleType="centerInside"
+          />
+        </div>
+      </DocsShow>
+
+      <h4><code style="font-weight: bold">'contain'</code> scale type</h4>
+
+      <p>Behaves like <code>'centerInside'</code> except it ensures that at least one axis of the image fits the container exactly.</p>
+
+      <p>The original aspect ratio is maintained. The image can be letterboxed. This mode may distort the image by enlarging it above its original size.</p>
+
+      <DocsShowCode language="html">
+        <div>
+          <KImg
+            src="hummingbird.jpg"
+            altText="A sitting hummingbird"
+            height="200"
+            width="100%"
+            maxWidth="500"
+            scaleType="contain"
+          />
+        </div>
+      </DocsShowCode>
+      <DocsShow block>
+        <div>
+          <KImg
+            :src="require('../assets/hummingbird CC BY-SA 4.0.jpg')"
+            altText="A sitting hummingbird"
+            height="200"
+            width="100%"
+            maxWidth="500"
+            scaleType="contain"
+          />
+        </div>
+      </DocsShow>
+
+      <h4><code style="font-weight: bold">'fitXY'</code> scale type</h4>
+
+      <p>Scales X and Y axis of the image independently, so that the image matches the container exactly.</p>
+
+      <p>This mode may distort the image as its original aspect ratio is ignored and the image won't be letterboxed. It could also distort the image by enlarging it above its original size.</p>
+
+      <DocsShowCode language="html">
+        <div>
+          <KImg
+            src="hummingbird.jpg"
+            altText="A sitting hummingbird"
+            height="200"
+            width="100%"
+            maxWidth="500"
+            scaleType="fitXY"
+          />
+        </div>
+      </DocsShowCode>
+      <DocsShow block>
+        <div>
+          <KImg
+            :src="require('../assets/hummingbird CC BY-SA 4.0.jpg')"
+            altText="A sitting hummingbird"
+            height="200"
+            width="100%"
+            maxWidth="500"
+            scaleType="fitXY"
+          />
+        </div>
+      </DocsShow>
+
+      <h2>Aspect ratio</h2>
+
+      <p>Note that ratio styles are based on the width information, therefore it needs to be available in some way. For example, it could be provided directly to <code>KImg</code>, or you could ensure that its parent element has width by setting it explicitly or by using a block element.</p>
+
+      <p>You may combine aspect ratio with any of the scale types.</p>
+
+      <DocsShowCode language="html">
+        <div>
+          <KImg
+            src="hummingbird.jpg"
+            altText="A sitting hummingbird"
+            aspectRatio="4:3"
+          />
+        </div>
+      </DocsShowCode>
+      <DocsShow block>
+        <div>
+          <KImg
+            :src="require('../assets/hummingbird CC BY-SA 4.0.jpg')"
+            altText="A sitting hummingbird"
+            aspectRatio="4:3"
+          />
+        </div>
+      </DocsShow>
+
+      <!-- 
+
       <div>
         The <DocsLibraryLink component="KImg" /> component displays images based on an image source and optional image
         dimensions provided by the implementer.
@@ -77,8 +284,9 @@
           />
         </DocsShowCode>
 
-      </div>
+      </div> -->
     </DocsPageSection>
+
   </DocsPageTemplate>
 
 </template>
@@ -95,21 +303,23 @@
 
   .img-example-1 {
     display: flex;
+    flex-wrap: wrap;
     margin-top: 20px;
   }
 
-  .img-example-2 {
-    margin-top: 20px;
-    margin-bottom: 20px;
-  }
+  /* 
+    .img-example-2 {
+      margin-top: 20px;
+      margin-bottom: 20px;
+    }
 
-  .img-example-2 > div {
-    display: flex;
-  }
+    .img-example-2 > div {
+      display: flex;
+    }
 
-  .img-example-2 > div > div {
-    margin-top: 30px;
-  }
+    .img-example-2 > div > div {
+      margin-top: 30px;
+    } */
 
 </style>
 
diff --git a/lib/KImg.vue b/lib/KImg.vue
index 829e6f5cf..fa3787d41 100644
--- a/lib/KImg.vue
+++ b/lib/KImg.vue
@@ -1,19 +1,57 @@
 <template>
 
-  <div :style="containerStyles">
-    <img
-      :src="src"
-      :alt="alternateText"
-      :style="imgStyles"
-    >
-    <slot></slot>
-  </div>
+  <span :style="rootContainerStyles">
+    <span :style="ratioContainerStyles">
+      <img
+        :src="src"
+        :alt="alternativeText"
+        :style="imgStyles"
+      >
+      <!-- TODO: Document slot -->
+      <slot></slot>
+    </span>
+  </span>
 
 </template>
 
 
 <script>
 
+  const ScaleTypes = {
+    CENTER_INSIDE: 'centerInside',
+    CONTAIN: 'contain',
+    FIT_XY: 'fitXY',
+  };
+  const RATIO_REGEX = /^(\d+):(\d+)$/;
+
+  function isValidScaleType(value) {
+    return value && Object.values(ScaleTypes).includes(value);
+  }
+
+  /**
+   * Extract x and y from an aspect ratio x:y
+   *
+   * @param {String} value aspect ratio in "x:y" format
+   * @returns {Object} { x, y }
+   */
+  function extractAspectRatio(value) {
+    const match = value.match(RATIO_REGEX);
+    return { x: match[1], y: match[2] };
+  }
+
+  /**
+   * @returns {Boolean} Returns true if value satisfies "x:y"
+   *                    format where x and y are numbers
+   */
+  function isValidAspectRatio(value) {
+    return RATIO_REGEX.test(value);
+  }
+
+  /**
+   * Displays an image and provides additional functionality
+   * to manipulate it such as setting an aspect ratio,
+   * scaling, and more.
+   */
   export default {
     name: 'KImg',
     props: {
@@ -25,80 +63,203 @@
         default: null,
       },
       /**
-       * Alternate text for the image. This is required and will throw a warning when it's not provided (empty) unless isDecorative is true
+       * Alternative text for the image. Required unless `isDecorative` is true.
        */
       altText: {
         type: String,
         default: '',
       },
       /**
-       * Sets the image as decorative. This sets the alt image property to an empty string.
+       * Sets the image as decorative.
        */
       isDecorative: {
         type: Boolean,
         default: false,
       },
       /**
-       * Sets the height for the container
+       * Sets the height of the image container
        */
       height: {
         type: [Number, String],
         default: undefined,
       },
       /**
-       * Sets the width for the container
+       * Sets the width of the image container
        */
       width: {
         type: [Number, String],
         default: undefined,
       },
       /**
-       * Sets the maximum height for the container
+       * Sets the maximum height of the image container
        */
       maxHeight: {
         type: [Number, String],
         default: undefined,
       },
       /**
-       * Sets the minimum height for the container
+       * Sets the minimum height of the image container
        */
       minHeight: {
         type: [Number, String],
         default: undefined,
       },
       /**
-       * Sets the maximum width for the container
+       * Sets the maximum width of the image container
        */
       maxWidth: {
         type: [Number, String],
         default: undefined,
       },
       /**
-       * 	Sets the minimum width for the container
+       * 	Sets the minimum width of the image container
        */
       minWidth: {
         type: [Number, String],
         default: undefined,
       },
+      /**
+       * Sets the ratio of the width(w) to the height(h)
+       * of the image container. The required format is `w:h`.
+       */
+      aspectRatio: {
+        type: String,
+        default: undefined,
+        validator: isValidAspectRatio,
+      },
+      /**
+       * Specifies how an image should be scaled within the container.
+       * Can be one of  `'centerInside'` (default), `'contain'`, or `'fitXY'`.
+       * See the documentation examples.
+       */
+      scaleType: {
+        type: String,
+        default: 'centerInside', // needs to be duplicated rather than using ScaleTypes.CENTER_INSIDE, otherwise it doesn't render correctly in the auto-generated Props documentation
+        validator: isValidScaleType,
+      },
     },
     computed: {
-      alternateText() {
+      ratio() {
+        return extractAspectRatio(this.aspectRatio);
+      },
+      alternativeText() {
         return this.isDecorative ? '' : this.altText;
       },
-      containerStyles() {
+      baseStyles() {
+        return {
+          rootContainer: {
+            display: 'block',
+            backgroundColor: this.$themePalette.grey.v_200,
+            height: this.validateAndFormatUnits(this.height),
+            width: this.validateAndFormatUnits(this.width),
+            maxHeight: this.validateAndFormatUnits(this.maxHeight),
+            minHeight: this.validateAndFormatUnits(this.minHeight),
+            maxWidth: this.validateAndFormatUnits(this.maxWidth),
+            minWidth: this.validateAndFormatUnits(this.minWidth),
+          },
+          ratioContainer: {
+            display: 'block',
+          },
+          img: {
+            display: 'block',
+          },
+        };
+      },
+      scaleStyles() {
+        const scaleKind = isValidScaleType(this.scaleType) ? this.scaleType : ScaleTypes.CONTAIN;
+        const scaleStyles = {
+          [ScaleTypes.CONTAIN]: {
+            rootContainer: {},
+            ratioContainer: {
+              height: '100%',
+              width: '100%',
+            },
+            img: {
+              objectFit: 'contain',
+              height: '100%',
+              width: '100%',
+            },
+          },
+          [ScaleTypes.FIT_XY]: {
+            rootContainer: {},
+            ratioContainer: {
+              height: '100%',
+              width: '100%',
+            },
+            img: {
+              width: '100%',
+              height: '100%',
+            },
+          },
+          [ScaleTypes.CENTER_INSIDE]: {
+            rootContainer: {
+              display: 'flex',
+              justifyContent: 'center',
+              alignItems: 'center',
+            },
+            ratioContainer: {},
+            img: {
+              maxWidth: '100%',
+              maxHeight: '100%',
+            },
+          },
+        };
+        return scaleStyles[scaleKind];
+      },
+      ratioStyles() {
+        if (!this.aspectRatio) {
+          return {
+            rootContainer: {},
+            ratioContainer: {},
+            img: {},
+          };
+        }
+        const paddingTopInPercent = (this.ratio.y / this.ratio.x) * 100;
+        return {
+          rootContainer: {},
+          ratioContainer: {
+            position: 'relative',
+            display: 'block',
+            height: 0,
+            width: '100%',
+            padding: `${paddingTopInPercent}% 0 0`,
+          },
+          img: {
+            position: 'absolute',
+            display: 'block',
+            maxWidth: '100%',
+            maxHeight: '100%',
+            margin: 'auto',
+            top: 0,
+            right: 0,
+            bottom: 0,
+            left: 0,
+            zIndex: 2,
+          },
+        };
+      },
+      rootContainerStyles() {
+        // order matters
+        return {
+          ...this.baseStyles.rootContainer,
+          ...this.scaleStyles.rootContainer,
+          ...this.ratioStyles.rootContainer,
+        };
+      },
+      ratioContainerStyles() {
+        // order matters
         return {
-          height: this.validateAndFormatUnits(this.height),
-          width: this.validateAndFormatUnits(this.width),
-          maxHeight: this.validateAndFormatUnits(this.maxHeight),
-          minHeight: this.validateAndFormatUnits(this.minHeight),
-          maxWidth: this.validateAndFormatUnits(this.maxWidth),
-          minWidth: this.validateAndFormatUnits(this.minWidth),
+          ...this.baseStyles.ratioContainer,
+          ...this.scaleStyles.ratioContainer,
+          ...this.ratioStyles.ratioContainer,
         };
       },
       imgStyles() {
+        // order matters
         return {
-          width: '100%',
-          height: '100%',
+          ...this.baseStyles.img,
+          ...this.scaleStyles.img,
+          ...this.ratioStyles.img,
         };
       },
     },