Aspect Ratio @astryx-svelte/core v0.5.2 · AspectRatio
Usage
Maintains a fixed width-to-height ratio for its children as its container resizes. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions. It takes its width from the container and derives its height from the ratio, so it needs an ancestor with a definite width.ts
Best practices
| Guidance | Practices |
|---|---|
| Do | Express the ratio as a fraction like 16/9 or 4/3 for readability. |
| Do | Use for media that needs consistent proportions across screen sizes. |
| Do | Use fit="cover" for images and video so the component sizes the child; the child should not repeat width/height/objectFit styles. |
| Do | Pass one child. With fit set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child. |
| Do | Describe media children with alt, or alt="" when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description. |
| Do | For a breakpoint-dependent ratio, override the ratio responsively: pass an aspectRatio rule via xstyle (StyleX), or override aspect-ratio from your own unlayered CSS under a @media/@container rule; component styles live in the astryx-base cascade layer, so unlayered consumer CSS wins. Give an xstyle rule a default branch alongside the conditional one ({default: 3, '@container ...': '3 / 2'}); with only the conditional branch the ratio is unset outside the query and the box collapses. |
| Don't | Use for general layout containers; use standard layout components instead. |
| Don't | Nest AspectRatio containers; one level is sufficient. |
| Don't | Constrain the height on its own. The width comes from the container, so a height or maxHeight by itself clamps the box off ratio; pair it with width: "auto" to size from the height instead. |
| Don't | Place it in a shrink-to-fit parent such as inline-flex, width: fit-content or a floated box. It contributes no intrinsic width there and collapses to zero. |
Examples
Common configurations, variations, and states.AspectRatio — Circle Image
Circular container via shape="ellipse" with ratio={1}, ideal for avatars and profile images.
AspectRatio — Image Gallery
Grid of images with consistent 4:3 aspect ratios.
AspectRatio — Square Image
1:1 square aspect ratio, ideal for avatars and Instagram-style images.
AspectRatio — 16:9 Widescreen Image
16:9 widescreen aspect ratio wrapping an image.
AspectRatio — Loading Skeleton
Aspect ratio container with a skeleton loading placeholder.