Skip to main content

Your opinion matters! Together with you, we want to continuously improve KoliBri. Share your ideas, wishes, or suggestions—quickly and easily.

Image

This documentation is currently being revised and is in beta status. Content may still change.
This component is being retested for accessibility. The full test is still pending and can only be completed after a release.

Synonyms: Img, Thumbnail

Description: The Image component renders images and supports responsive display with different resolutions, pixel densities, and file formats. It provides optimized loading through lazy loading and ensures full accessibility with alternative texts.

Example​

Basic display of an image with the required alternative text:

<KolImage _alt="Sample image" _loading="lazy" _src="/assets/sample-image.png" />

Accessibility​

  • Alternative text required: The _alt attribute is mandatory and is read by screen readers. For purely decorative images it can be empty (_alt=""), which causes assistive technologies to ignore it.
  • Fallback for missing images: The alternative text is displayed by browsers if the image cannot be loaded or is unavailable.
  • Semantically correct: The component uses native HTML5 <img> elements and supports all standard image formats and browser features.

Usage​

Best Practices / Recommendations​

  • Meaningful alternative texts: Write concise descriptions that convey the content and purpose of the image. Avoid "Image of..." or generic descriptions.
  • Decorative images: Leave _alt empty for purely decorative images that carry no semantic information.
  • Responsive images: Use _srcset and _sizes for different device resolutions and pixel densities to save bandwidth and deliver sharp images on high-resolution displays.
  • Modern file formats: Use _srcset with different file formats (e.g. WebP for modern browsers, JPEG as fallback) to optimize performance.
  • Use lazy loading: Set _loading="lazy" for images outside the initial viewport to improve page loading performance.
  • Eager loading for critical images: Use _loading="eager" only for images in the visible area (e.g. logo, hero image) that should be loaded immediately.

Use Cases​

  • Product images and galleries in e-commerce applications
  • User photos and avatars (in combination with other components)
  • Illustrations and icons to visualize content
  • Hero images and banner graphics on landing pages
  • Responsive images in articles, blog posts or documentation
  • Background images and branding elements

FAQ​

When should I use _srcset? Use _srcset when you want to provide the same image in different resolutions or sizes. This allows browsers to select the best variant based on device resolution and viewport size.

What is the difference between _loading="eager" and _loading="lazy"? eager loads the image immediately when the page loads. lazy delays loading until just before the image appears in the viewport. lazy is the default and improves page loading performance.

Can I use arbitrary image formats? Yes, all common formats are supported (PNG, JPEG, WebP, SVG, GIF etc.). Use _srcset with different formats for maximum browser compatibility and performance.

Construction / Technical​

Playground​

<KolImage _alt="Sample image" _loading="lazy" _src="/assets/sample-image.png" />

Features (with Code)​

Image source​

The image source is set via the required _src attribute. This is the fallback URL used when _srcset is not supported or no suitable variant is available.

<KolImage _alt="Sample image" _loading="lazy" _src="/assets/sample-image.png" />

Alternative text​

The required _alt attribute provides a text description or alternative for the image. For decorative images it can be empty.

<KolImage _alt="Example image description" _loading="lazy" _src="/assets/sample-image.png" />

Responsive images with Srcset and Sizes​

With _srcset different image versions can be specified for different resolutions, pixel densities and file formats. The _sizes attribute helps the browser understand what widths the image will have at different viewport sizes.

<KolImage _alt="Sample image" _loading="lazy" _sizes="(max-width: 600px) 100vw, 50vw" _src="/assets/sample-image.png" _srcset="/assets/image-small.png 600w, /assets/image-large.png 1200w" />

Loading behavior​

The _loading attribute controls when the browser loads the image. lazy is the default and improves performance, eager should only be used for images in the visible area.

<KolImage _alt="Sample image" _loading="lazy" _src="/assets/sample-image.png" />

Available values:

  • lazy: Defers loading until the viewport is reached (default)
  • eager: Immediate loading when entering the page

API​

Overview​

The Image component renders an image with support for responsive loading via srcset and sizes, lazy loading, and accessible alternative text.

Properties​

PropertyAttributeDescriptionTypeDefault
_alt (required)_altSets the alternative text of the image.stringundefined
_loading_loadingDefines the loading mode for the image."eager" | "lazy" | undefinedundefined
_sizes_sizesDefines the image sizes for different screen resolutions, supporting _srcset.string | undefinedundefined
_src (required)_srcSets the image src attribute to the given string.stringundefined
_srcset_srcsetSets a list of source URLs with widths of the images.string | undefinedundefined