FitScreen
fit-screenScales a fixed design canvas to fit, cover, or stretch within its container.
Usage
Basic usage
Scale the large-screen content with a fixed design size (default 1920×1080) into any parent container and center it proportionally.
<div className="h-56 w-full overflow-hidden rounded-lg border">
<FitScreen designWidth={1920} designHeight={1080}>
{/* Your 1920×1080 large screen content */}
</FitScreen>
</div>fit · No cutting to the same ratio
Default mode: Use min zoom, the content is completely visible, and edges may be left around.
<FitScreen mode="fit">
{/* Large screen content */}
</FitScreen>cover · Fully covered and can be cut
Take max and scale it to fill the container in equal proportions, and the excess part will be cut off.
<FitScreen mode="cover">
{/* Large screen content */}
</FitScreen>stretch · Non-equal ratio
Independent horizontal and vertical scaling fills the container, and the content may be deformed.
<FitScreen mode="stretch">
{/* Large screen content */}
</FitScreen>When to use
Use FitScreen when content has been laid out against a fixed design canvas, such as a 1920×1080 operations dashboard, and the entire canvas must scale within an arbitrary parent. Use Viewport when content should reflow at container breakpoints instead of scaling, or AspectRatio when a single element only needs a fixed ratio.
Import
import { FitScreen, computeFit } from "@hulianui/ui"Props
| Name | Type | Default | Description |
|---|---|---|---|
| designWidth | number | 1920 | Design-canvas width. |
| designHeight | number | 1080 | Design-canvas height. |
| mode | "fit" | "cover" | "stretch" | "fit" | fit preserves the full canvas and may letterbox; cover fills the parent and may crop edges; stretch fills both axes and may distort content. |
| className | string | — | The outer container class name. |
computeFit(input: FitInput) is the pure scaling function used after ResizeObserver measures the parent. It accepts { outerW, outerH, designW, designH, mode } and can be tested independently.
Slots
| Slot | Type | Description |
|---|---|---|
| children* | ReactNode | Content laid out at the fixed design dimensions. |
Usage guidelines
- Scaling uses `transform: scale`. Headless/CDP screenshot coordinates may not align with real click geometry. Account for this in visual and interaction tests; see [[recharts-headless-screenshot-blank-clippath-animation-starved]] and [[turbopack-dev-cold-route-blank-cdp-screenshot-warm-first]]. Use
dispatchEventif coordinate clicks are inaccurate. - Guard detached refs before writing styles. During StrictMode remounts,
<Activity>, or Offscreen reconnection,ref.currentcan remain truthy after its style target is detached. See [[react-offscreen-reconnect-detached-ref-style-crash]]; checkif (!el?.style) returnbefore writing. - Keep
designWidthanddesignHeightconsistent with the dimensions used to lay out the children. A mismatch produces the wrong scale and can cause clipping or unexpected empty space.
Related
Layout · AdminLayout · ScrollArea · Viewport · Resizable · AspectRatio
Playground
<FitScreen designWidth={1920} designHeight={1080} mode="fit">
{/* Your 1920×1080 large screen content */}
</FitScreen>