(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)

Image Displayer

Overview

• The Dynamic Image Displayer component shows images on a page.
• It supports different sizing and display strategies.
• Developers can set custom dimensions or let the component auto-size.
• Events allow interactions such as clicks and lifecycle handling.
• Visibility and authorization settings control when and for whom the image is shown.

Specs

Tokens

Structure

• The component consists of an image element inside a container.
• The structure is defined by the image source set with imageUrl.
• Scrollbar behavior defines how oversized images are handled.

(Configured in General Properties)

• displayName – Sets the display name of the component shown in the structure panel. This allows for easy identification of the component within the application structure. Example: "Product Image".
• source – Specifies the URL path to the image that should be displayed. This can be an absolute URL to an external image or a relative path to an image within your application. Supports template expressions for dynamic image sources based on context values. Example: "https://example.com/images/product.jpg" or "{{context.product.imageUrl}}".

(Configured in Visual Properties)

• alt – Defines alternative text description for the image, important for accessibility and when the image cannot be loaded. This text will be read by screen readers and displayed if the image fails to load. Example: "Red sports car on mountain road".

(Configured in Visibility Properties)

• displayConditions – Defines conditions for displaying the component. This allows showing the image only when certain conditions are met, such as when specific data is available or meets certain criteria. Example:

  [ 
    { "field": "context.product.hasImage", "operator": "equals", "value": true } 
  ]

Styling

(Configured in Visual Properties)

• scrollbar – Controls whether scrollbars appear when the image exceeds its container dimensions.
• disableScrollbar – Hides scrollbars even if the image is larger than its container. Example: false.
• paddingClass – Configures the padding space around the component using CSS classes. For example, "p-3" adds medium padding on all sides of the image. Example: "p-3".
• width – Sets the width of the image when using the useStaticSize strategy. This property accepts standard CSS size values. Example: "300px" or "50%".
• widthAuto – Automatically calculates the width of the component based on its content. This is useful when you want the image container to size itself to the content rather than defining a fixed width. Example: true.
• height – Sets the height of the image when using the useStaticSize strategy. This property accepts standard CSS size values. Example: "200px" or "auto".
• heightAuto – Automatically calculates the height of the component based on its content. This is useful when you want the image container to size itself to the content rather than defining a fixed height. Example: true.

Actions & Variants

(Configured in Events)

• events – Configures the events that the component can trigger and respond to:
• ON_IMAGE_CLICK – Triggered when the user clicks on the image. Can be used to open larger versions of the image, navigate to detail pages, or trigger other actions.
• ON_INIT – Triggered when the component is initialized. Can be used to perform setup operations.
• ON_DESTROY – Triggered when the component is removed from the DOM. Useful for cleanup operations.
• ON_GLOBAL_PARAMETERS_CHANGE – Triggered when global parameters that might affect the component change.

(Configured in Visual Properties)

• resizeImageStrategy – Determines how the image is sized and displayed within its container. Options include:
• fitToContainer – Scales the image to fit within the container while maintaining aspect ratio.
• useStaticSize – Uses the specified width and height dimensions.
• fillWholeContent – Stretches the image to fill the entire container, potentially distorting the aspect ratio.
• useRealSize – Displays the image at its original dimensions. Example: "fitToContainer".

Tests

(Configured in Testing Hooks)

• id – Specifies a unique identifier for the component used for programmatic access. Example: "productMainImage".
• dataTestId – Sets the testing hook ID for automated testing. This helps QA teams locate and interact with the component in automated tests. Example: "product-image-component".
• enableAsHotspot – Enables the component as a guided tour hotspot. When set to true, the component can be highlighted during guided tours to help users learn the interface. Example: true.
• guidedTourHotSpotTitle – Sets the title for the guided tour hotspot, supporting translations. Example: {"en-US": "Product Image", "es-ES": "Imagen del Producto"}.
• guidedTourHotSpotDescription – Sets the description for the guided tour hotspot, supporting translations. Example: {"en-US": "Click on the image to see larger view", "es-ES": "Haga clic en la imagen para ver una vista más grande"}.

Authorization

(Configured in Authorization)

• visibilityPolicySetId – Determines whether the component is displayed based on a policy set. This allows showing the image only to users with specific permissions. Example: "contentViewerPolicy".

Links

• Figma: tba
• Live style guide: tba

Guidelines

Usage

• Bind visual content with imageUrl (template expressions allowed) and always provide an appropriate alt.
• Choose an explicit sizing mode via resizeImageStrategy:
• fitToContainer for aspect-preserving photos/illustrations.
• useStaticSize with width/height for predictable thumbnails.
• useRealSize for pixel-accurate assets.
• fillWholeContent only when distortion is acceptable.
• Control when the component renders with displayConditions; restrict access with visibilityPolicySetId.

Sizing & Layout

• Prefer intrinsic sizing when appropriate using widthAuto / heightAuto.
• For fixed dimensions, pair resizeImageStrategy: "useStaticSize" with width and/or height.
• Preserve aspect ratio with resizeImageStrategy: "fitToContainer"; reserve "fillWholeContent" for deliberate stretch.
• Use paddingClass to add touch/click comfort around interactive images (ON_IMAGE_CLICK).
• Manage overflow with disableScrollbar: keep it false when content may exceed bounds (e.g., useRealSize).

Interactions & Events

• ON_IMAGE_CLICK: open a larger image, navigate, or emit analytics.

Visibility & Authorization

• Enforce role/permission gating with visibilityPolicySetId.
• Suppress empty/broken states with displayConditions (e.g., require non-empty imageUrl).
• Expose stable hooks for automation via id and dataTestId.

Content & Localization

• Provide meaningful alt for informative images; use empty alt ("") for decorative content.
• Use enableAsHotspot with localized guidedTourHotSpotTitle and guidedTourHotSpotDescription for guided tours.
• Keep displayName descriptive for authoring clarity (non-user-facing).

Dos & Don’ts

Accessibility

• Text alternatives: define alt text ascordingly.
• For interactive images, align alt phrasing with the ON_IMAGE_CLICK outcome (e.g., “Opens larger view”).
• Overflow access: set disableScrollbar: false when content may exceed bounds (e.g., with useRealSize).
• Aspect integrity: prefer resizeImageStrategy: "fitToContainer" when distortion would harm comprehension.
• Localization for guidance: when enableAsHotspot is true, supply translated guidedTourHotSpotTitle / guidedTourHotSpotDescription.
• Prevent empty graphics from being announced by gating display with displayConditions when imageUrl is missing.
• Improve hit comfort on touch by adding paddingClass around clickable imagery.