FitBox
Draws its content in the largest box of a given aspect ratio that fits, always centered.
import { FitBox } from "@butteryui/core";Demo
When to use it
Use it for
- Stage canvases, media previews, anything that keeps its shape while the space around it changes
Not for
- Content that should scroll when it doesn't fit: use a scroll container
Examples
Portrait preview
A tall 9:16 slide's preview that fills the height of a wide area without overflowing it.
Stage canvas
A slide editor's stage: the slide takes the shape you pick and stays centered, 32px clear of the edges.
Variants and states
Ratios
The same space holding three ratios; each box is as large as fits.
16:9
1:1
9:16
Props
FitBox
| Prop | Type | Default | Description |
|---|---|---|---|
ratiorequired | number | Width ÷ height of the content box, such as 16 / 9. Must be a positive number. | |
inset | SpaceValue | 0 | Least space between the content box and the edges, on the spacing scale. Defaults to 0. |
contentProps | ComponentPropsWithRef<"div"> | Props for the content box itself, such as a ref to measure it. | |
children | ReactNode | What to draw in the content box; it fills the box. |
It also takes ComponentPropsWithRef<"div">.
Accessibility
No role of its own; the content box is a plain div.
It takes no keyboard input of its own.
Motion
It doesn't move.
With reduced motion: Nothing changes.
Layout
It fills its parent, which needs a definite height (a sized grid or flex cell, or an explicit block size), and draws its content in the largest box of its ratio that fits inside the inset, centered. The content box follows resizes without JavaScript and never overflows, and its child fills it. It has no hit area of its own.