Docs

Main site

Installation Browser support Extend config MCP server
Validation Page speed testing Responsive design
Accordion Aspect Ratio Avatar Badge Banner Bento Grid Blockquote Breadcrumbs Button Callout Card Drawer Dropdown Link Modal Navbar Navblock Pagination Popover Progress Separator Tabs Timeline Toast Tooltip
Checkbox Datepicker File upload Form field Input Label OTP Radio Range Select Textarea Toggle
Header Footer
Accordion Auth Checkbox & Radio Content Drawers Features Modals Statistics & Metrics Teams
Address Contact number Currency symbol Date Emirates ID Name
Close
Home Documentation Components Aspect Ratio

Aspect Ratio

An Aspect Ratio component enforces a specific width-to-height ratio on its slotted content. Use it to wrap images, videos, and iframes that should hold a consistent shape regardless of viewport size — preventing layout shift as media loads. It is a layout primitive with no visual styling of its own.

Layout
Status
Active
Introduced
4.0.x
View source code

Options

The ratio property accepts either a small set of named presets, or any custom n/m ratio string.

Sheikh Zayed Grand Mosque dome detail Abu Dhabi skyline at dusk Dubai cityscape

Named presets

Only three strings are truly special-cased in the component: auto lets the slotted content size itself naturally (left→right: square, video, auto shown here); square enforces a 1:1 box; video enforces 16:9. Every other ratio — including common ones like 4/3 or 21/9 — is not a separately-recognised preset, it is just a custom n/m string handled by the same general rule below.

Dubai cityscape, 4 by 3 crop Panoramic view of the Burj Khalifa at night

Custom ratios

Any n/m string is valid — useful for ultrawide hero banners (21/9, right) or traditional photo formats (4/3, left). The component validates the format with a regular expression and falls back to auto if the string is malformed.

Fit modes

The fit property controls how slotted media is sized inside the container — it maps directly to CSS object-fit. Use cover (default) for imagery that should fill the box and crop as needed. Use contain when the whole image must stay visible, such as a logo or diagram, accepting letterboxing if the source ratio differs.

fit="cover" (default)

Abu Dhabi skyline, cover fit

fit="contain"

Abu Dhabi skyline, contain fit
<aegov-aspect-ratio ratio="square" fit="cover">
  <img src="https://images.unsplash.com/photo-1518684079-3c830dcef090?w=600" alt="Abu Dhabi skyline" />
</aegov-aspect-ratio>

<aegov-aspect-ratio ratio="square" fit="contain">
  <img src="https://images.unsplash.com/photo-1518684079-3c830dcef090?w=600" alt="Abu Dhabi skyline" />
</aegov-aspect-ratio>

Embedded video and iframes

aegov-aspect-ratio is the recommended way to embed responsive video players and map iframes — it guarantees the embed fills its container at the chosen ratio without a legacy padding-bottom hack. Always set a title on the iframe; the component warns in the console if one is missing.

<aegov-aspect-ratio ratio="video">
  <iframe
    src="https://www.youtube.com/embed/dQw4w9WgXcQ"
    title="Sample embedded video"
    allowfullscreen></iframe>
</aegov-aspect-ratio>

Responsive ratio

ratio accepts a Tailwind-style responsive string with breakpoint prefixes (xs, sm, md, lg, xl, 2xl). Each segment overrides smaller breakpoints — the example below is square on phones, video from md up, and 21/9 from xl up. Resize the browser to see it adapt.

Panoramic view of the Burj Khalifa at night
<aegov-aspect-ratio ratio="square md:video xl:21/9">
  <img
    src="https://images.unsplash.com/photo-1582719508461-905c673771fd?w=1600"
    alt="Panoramic view of the Burj Khalifa at night" />
</aegov-aspect-ratio>

Avatar tile

Combine ratio="square" with extra-class for rounded corners to produce square staff-photo tiles for a directory or team listing.

Staff portrait Staff portrait Staff portrait Staff portrait
<aegov-aspect-ratio ratio="square" extra-class="rounded-lg">
  <img src="https://randomuser.me/api/portraits/men/32.jpg" alt="Staff portrait" />
</aegov-aspect-ratio>

RTL support

Aspect ratio is a purely geometric wrapper — it has no directional layout, padding, or margin of its own, so it renders identically inside a dir="rtl" container.

Usage

Here is the recommended usage of an aspect ratio on any website or application. These are recommended usage guides, however the developer must use the best practices of web and application development to accurately use this component.

Wrap any media that loads after the page does

Reserve space for images, video embeds, and map iframes before they finish loading, so the page does not jump as content arrives.

Match the ratio to the source content

Use video (16:9) for widescreen footage and square for avatar or thumbnail grids — an intentional mismatch between the ratio and the source image just means more cropping via fit="cover".

Use fit="contain" when no part of the source can be cropped

Logos, diagrams, and screenshots usually need to stay whole. cover (the default) crops to fill the box, which is wrong for content where every pixel matters.

Do not use it to fake a fixed-height crop for cropping's own sake

If content simply needs a hard pixel height with no aspect relationship to width, a plain CSS height is simpler and clearer than reaching for a ratio component.

Do not rely on it to fix a source image with the wrong orientation

fit="cover" will crop a portrait photo dropped into a video (landscape) box, often cutting off the subject. Re-crop or re-select the source image instead of masking the problem with the ratio box.

Do not skip title on embedded iframes

The component only logs a console warning on first load — it will not add a title for you, and iframes added later are not checked, so an untitled map or video embed can still reach production.

API reference

The following are the properties and references of an aspect ratio

aegov-aspect-ratio default properties

AttributeDescriptionTypeDefault

ratio

Aspect ratio to apply. A named preset (auto, square, video) or any custom n/m string such as 21/9. Accepts a Tailwind-style responsive string, e.g. "square md:video lg:21/9" — so write ratios without spaces (16/9, not 16 / 9), since spaces separate responsive tokens. Invalid values silently fall back to auto.

string

auto

fit

How slotted media (img, video, iframe) fits inside the container. Mirrors CSS object-fit. Applies only to direct children — media nested inside <picture>, <a> or another wrapper is not sized. Invalid values fall back to cover with a console warning.

cover | contain | fill | none | scale-down

cover

extra-class

Additional CSS classes merged onto the inner container (not the host element) — for example rounded-*, bg-*, borders or shadows. The component's own unlayered rules for position, width and overflow win over Tailwind utilities, so set width on the host instead.

string

undefined

Slots

SlotDescription

(default)

Media or content to be sized to the configured aspect ratio.

This component emits no custom events — it is a layout primitive with no interactive state of its own.

Pass-through attributes

AttributeNotesForwards to

aria-*

Not automatically forwarded. Apply directly to <aegov-aspect-ratio>.

n/a

data-*

Not automatically forwarded. Apply directly to <aegov-aspect-ratio>.

n/a

class, style, id

Allowed on the host. The host has no display rule of its own (it stays inline), so inside a flex or grid parent give it a width, e.g. class="w-full". Use extra-class to add classes to the inner container instead.

host element

Notes

The following notes are applicable of this component.

Built-in accessibility

  • The component introduces no roles, landmarks, or ARIA attributes of its own — it is purely a layout primitive. Slotted content (img, iframe, video) retains its native semantics.
  • Invalid ratio strings silently fall back to auto; invalid fit values fall back to cover and log a console warning during development.
  • The inner container uses overflow: clip with a 4px overflow-clip-margin instead of overflow: hidden. Focus rings on slotted interactive elements remain visible up to 4px outside the clipping boundary, satisfying WCAG SC 2.4.11 (Focus Not Obscured). Unlike overflow: hidden, overflow: clip does not create a new scroll container or stacking context.
  • On load, the component checks every slotted <iframe> for a title attribute and logs a console.warn if one is missing — surfacing the WCAG SC 4.1.2 requirement during development without breaking the page.

Developer responsibility

The following is required for a developer to add additionally or pay attention to regarding this component.

  • Provide meaningful alt text on slotted <img> elements. For purely decorative imagery, use alt="" so screen readers skip it.
  • Provide a title attribute on every embedded <iframe> (maps, video players) so assistive technology can announce the embed. The component only warns about a missing title in the console — it does not add one for you.
  • Provide accessible captions or a transcript for <video> content where required.

Additional notes

  • Controls that need a focus ring wider than 4px (the overflow-clip-margin value) should increase their own outline-offset accordingly, since content further than 4px outside the box is still clipped.