Aspect Ratio Box — OutSystems Forge Documentation

📋 Table of Contents

1. Overview & Description
2. Installation Guide
3. Component Properties Reference
4. Usage Examples
5. Troubleshooting Guide

1. Overview & Description <a name="overview"></a>

What is Aspect Ratio Box?

Aspect Ratio Box is a lightweight, zero-JavaScript Reactive Web Block for OutSystems that maintains a consistent aspect ratio for any content placed inside it. Built entirely with CSS using the classic padding-bottom percentage trick, it works reliably across all browsers and devices without any external dependencies.

Simply configure the ratio width and height values and drop any content — images, videos, iframes, cards, or custom widgets — inside the block's content placeholder. The box will always maintain the correct proportions regardless of screen size.

Key Features

• ✅ Fully configurable aspect ratio — any width:height combination
• ✅ Works with any content — images, videos, iframes, cards, custom widgets
• ✅ Zero JavaScript — pure CSS implementation
• ✅ Fixed width with pixel-perfect proportions
• ✅ Configurable background color
• ✅ Configurable border radius
• ✅ Configurable overflow behavior
• ✅ Lightweight — no performance impact
• ✅ No external libraries or CDN required
• ✅ Mobile compatible

Supported Platforms

Dependencies

How It Works

The component uses the padding-bottom percentage trick — a well-known CSS technique where padding-bottom as a percentage is always calculated relative to the element's width, not its height. This creates a box with a mathematically correct height based on the ratio:

PaddingBottom = (RatioHeight / RatioWidth) * 100

Examples:

Content is then placed inside an absolutely positioned inner container that fills 100% width and height of the outer box.

2. Installation Guide <a name="installation"></a>

Step 1 — Download from Forge

1. Go to OutSystems Forge
2. Search for Aspect Ratio Box
3. Click Install → Select your environment
4. Wait for installation to complete

Step 2 — Add Reference in Your Module

1. Open your module in Service Studio
2. Go to Manage Dependencies (Ctrl+Q)
3. Search for AspectRatioLib
4. Select and add:

5. Click Apply

Step 3 — Add to Your Screen

1. Open the screen where you want to use the component
2. In the widget toolbox find AspectRatioBox under UI Flows
3. Drag it onto your screen
4. Configure the Config input parameter
5. Drop your content inside the Content placeholder

Step 4 — Configure the Block

Create a Local Variable on your screen:

• Name: BoxConfig
• Data Type: AspectRatioConfig

In On Initialize set your values:

BoxConfig.RatioWidth      = 16
BoxConfig.RatioHeight     = 9
BoxConfig.Width           = 640
BoxConfig.BackgroundColor = "#000000"
BoxConfig.OverflowContent = "hidden"
BoxConfig.BorderRadius    = 8

Set the block's Config = BoxConfig

Step 5 — Add Content Inside the Placeholder

Click the Content placeholder inside the block and add your widgets:

• Image widget → set Width and Height to 100%
• Iframe widget → set Width and Height to 100%
• Any container or custom content

Step 6 — Publish and Test

1. Press Ctrl+P to publish
2. Open app in browser
3. Content should render with correct proportions

3. Component Properties Reference <a name="properties"></a>

Web Block: AspectRatioBox

Placeholder: Content

Drop any widget or content inside this placeholder. The content will fill 100% width and height of the aspect ratio box.

Structure: AspectRatioConfig

OverflowContent Values

4. Usage Examples <a name="usage"></a>

Example 1 — 16:9 YouTube Embed

Perfect for video embeds that maintain widescreen proportions:

BoxConfig.RatioWidth      = 16
BoxConfig.RatioHeight     = 9
BoxConfig.Width           = 640
BoxConfig.BackgroundColor = "#000000"
BoxConfig.OverflowContent = "hidden"
BoxConfig.BorderRadius    = 8

AspectRatioBox (Config = BoxConfig)
  └── Content Placeholder:
        └── Iframe
              URL:    "https://www.youtube.com/embed/VIDEO_ID"
              Width:  100%
              Height: 100%
              Border: 0

Result: A 640×360px video embed that always stays 16:9.

Example 2 — 4:3 Image Display

Great for product images or photo galleries:

BoxConfig.RatioWidth      = 4
BoxConfig.RatioHeight     = 3
BoxConfig.Width           = 400
BoxConfig.BackgroundColor = "#f5f5f5"
BoxConfig.OverflowContent = "hidden"
BoxConfig.BorderRadius    = 12

AspectRatioBox (Config = BoxConfig)
  └── Content Placeholder:
        └── Image Widget
              URL:    YourImageURL
              Width:  100%
              Height: 100%
              Style:  object-fit: cover

Result: A 400×300px image that is always perfectly 4:3.

Example 3 — 1:1 Square Card

Perfect for profile pictures, product thumbnails or square cards:

BoxConfig.RatioWidth      = 1
BoxConfig.RatioHeight     = 1
BoxConfig.Width           = 200
BoxConfig.BackgroundColor = "#ffffff"
BoxConfig.OverflowContent = "hidden"
BoxConfig.BorderRadius    = 100

AspectRatioBox (Config = BoxConfig)
  └── Content Placeholder:
        └── Image Widget (profile picture)
              Width:  100%
              Height: 100%
              Style:  object-fit: cover

Result: A perfect 200×200px circle profile picture.

Example 4 — 21:9 Cinematic Banner

For wide hero banners or cinematic image displays:

BoxConfig.RatioWidth      = 21
BoxConfig.RatioHeight     = 9
BoxConfig.Width           = 800
BoxConfig.BackgroundColor = "#1a1a1a"
BoxConfig.OverflowContent = "hidden"
BoxConfig.BorderRadius    = 0

Result: An 800×343px cinematic banner.

Example 5 — Portrait Mobile Preview

For showing mobile app screenshots or portrait content:

BoxConfig.RatioWidth      = 9
BoxConfig.RatioHeight     = 16
BoxConfig.Width           = 280
BoxConfig.BackgroundColor = "#f0f0f0"
BoxConfig.OverflowContent = "hidden"
BoxConfig.BorderRadius    = 24

Result: A 280×498px portrait box — perfect mobile screen mockup.

Example 6 — Multiple Cards in a Grid

Use in a list to ensure all cards maintain consistent proportions:

List Widget (Source: ProductList)
  └── List Item:
        └── AspectRatioBox
              Config:
                RatioWidth  = 4
                RatioHeight = 3
                Width       = 300
                BorderRadius = 8
              Content Placeholder:
                └── Image: Product.ImageURL

Result: All product cards maintain the same 4:3 ratio regardless of image dimensions.

Example 7 — Common Ratio Quick Reference

5. Troubleshooting Guide <a name="troubleshooting"></a>

❌ Issue: Content Not Filling the Box Completely

Cause: Content widget does not have 100% width and height.

Fix:Set Width and Height to 100% on your content widget:

Image widget:
  Width:  100%
  Height: 100%
  Style:  object-fit: cover

For containers, add inline style:

width: 100%; height: 100%;

❌ Issue: Box Height Looks Wrong

Cause: RatioWidth or RatioHeight values are zero or not set.

Fix:Always initialize both values in On Initialize:

BoxConfig.RatioWidth  = 16  ← Never set to 0
BoxConfig.RatioHeight = 9   ← Never set to 0

Setting either to 0 causes a division by zero and breaks the height calculation.

❌ Issue: Content Overflowing Outside the Box

Cause: OverflowContent is set to visible.

Fix:Set OverflowContent = "hidden" to clip content within the box boundaries:

BoxConfig.OverflowContent = "hidden"

❌ Issue: Box Too Wide on Mobile

Cause: Fixed pixel width exceeds mobile screen width.

Fix:The component's CSS already handles this with:

@media (max-width: 480px) {
    .ar-outer-box {
        width: 100% !important;
    }
}

On mobile the box automatically fills the full screen width while maintaining its aspect ratio.

❌ Issue: Image Appears Stretched or Distorted

Cause: Image is forced to fill the box without maintaining its own proportions.

Fix:Add object-fit: cover to the image widget's style:

object-fit: cover;
width: 100%;
height: 100%;

This crops the image to fill the box while preserving its aspect ratio.

❌ Issue: Border Radius Not Showing on Content

Cause: Content overflows outside the border radius.

Fix:Make sure OverflowContent = "hidden" — this clips the content to the rounded corners:

BoxConfig.OverflowContent = "hidden"
BoxConfig.BorderRadius    = 12

❌ Issue: Iframe Not Loading Inside the Box

Cause: The iframe src URL may not allow embedding.

Fix:

1. Check the URL allows iframe embedding (some sites block this)
2. Make sure the iframe has width: 100% and height: 100%
3. Set border: 0 on the iframe to remove default borders
4. For YouTube use the embed URL format:

https://www.youtube.com/embed/VIDEO_ID

Not the regular watch URL.

💡 General Tips

• Always set both RatioWidth and RatioHeight — never leave them as 0
• Use object-fit: cover on images for best results
• Use OverflowContent = "hidden" for most use cases
• For circular elements set BorderRadius to half the Width value
• Test with different screen sizes — the mobile responsive CSS handles width automatically
• Use consistent ratios across a list/grid for a clean, professional layout

Documentation Version: 1.0.0Component Version: 1.0.0Last Updated: 2026Author: — (your name here)