Aspect ratio picker

Pick the shape of an image before it is generated. Every option draws its ratio, so 9:16 and 16:9 never get confused. A segmented row or a compact popover grid, with a lockable custom size.

Markdown

On this page

The segmented row, with a frame that takes the shape you pick and its size in pixels.

Installation

$ pnpm dlx shadcn@latest add https://chatcn.dev/r/aspect-ratio-picker.json

Usage

tsx

import { AspectRatioPicker } from "@/components/ui/chatcn/aspect-ratio-picker"

<AspectRatioPicker value={ratio} onValueChange={setRatio} />
<AspectRatioPicker layout="popover" value={ratio} onValueChange={setRatio} />

Values are "W:H" strings. A preset value selects that preset; anything else is a custom size in pixels, such as "1536:1024". parseAspectRatio(value) turns either into { width, height, ratio }. Custom sizes snap to a multiple of step (default 8) when a field loses focus, and stay within min and max.

Examples

Compact trigger

The popover layout in a prompt toolbar: a grid of ratios that opens from the trigger.

States

Ratios a model does not support, a custom size snapped to 64 and disabled.

Props

Prop	Type	Notes
`value`, `defaultValue`, `onValueChange`	`string`	Default `"1:1"`
`options`	`Array<string \| { value, label?, name?, disabled? }>`	Default 1:1, 4:5, 3:2, 4:3, 16:9, 9:16, 21:9
`allowCustom`	`boolean`	Adds Custom with width and height. Default `true`
`min`, `max`	`number`	Custom bounds in px. Default 256 and 4096
`step`	`number`	Custom sizes snap to this on blur. Default 8
`defaultCustom`	`string`	Where Custom starts. Default `"1536:1024"`
`layout`	`"inline" \| "popover"`	Default `inline`
`disabled`	`boolean`
`label`	`string`	Names the radio group. Default "Aspect ratio"
`open`, `onOpenChange`, `side`, `align`		Popover layout only

Keyboard

Key	Action
`Tab`	Move to the selected ratio. The group is one tab stop
Arrow keys	Select the next or previous ratio, skipping disabled ones. In the grid, up and down move by row
`Home`, `End`	First or last ratio
`Enter`	In the popover: choose and close
`ArrowUp`, `ArrowDown` in a size field	Add or remove one step
`Escape`	Close the popover

Accessibility

A radio group with roving focus. Each radio says the ratio and its name, for example 16:9, widescreen.
The lock is a toggle button with aria-pressed. Out of range sizes mark the field invalid and say the limits.
Options and the trigger grow to 44 px on touch screens.

Motion

Selection is instant: it is a frequent, keyboard-friendly control.
The popover grows from its trigger in 180 ms and does not animate when opened from the keyboard. The lock icon swaps with a 150 ms blur crossfade.