# Image cropper

A React component in [Beamline](https://beamline.io/)'s [Form controls](https://beamline.io/components/forms) category. Live demo: https://beamline.io/components/image-cropper

Frame a picture before it is saved: a fixed window (square, round for avatars, wide for covers, or free with handles) over the picture, which you drag, zoom with the slider, wheel or a pinch, and turn a quarter at a time; it always covers the window, thirds lines show while you move it, and the arrow keys, + and − and R do the same from the keyboard. cropImage turns the result into a file.

## Use it for

- Before saving a profile picture, a workspace logo or a cover image: the person chooses what part of the picture shows.
- Fitting any uploaded picture to the shape it will be shown in.

## Not for

- Choosing the files ([file-dropzone](https://beamline.io/components/file-dropzone), then crop the picture chosen).
- Comparing two pictures ([image-compare](https://beamline.io/components/image-compare)).
- Viewing pictures full screen ([lightbox](https://beamline.io/components/lightbox)).

## Anatomy

- stage: the picture under a dimmed surround, the crop window cut out of it (a circle for round), a size container that keeps its own aspect
- thirds lines inside the window, shown while the picture is moved or zoomed
- handles at the window's corners when the aspect is free
- toolbar: zoom slider between a smaller and a larger picture glyph, Rotate, Reset
- live line for assistive tech: zoom and rotation after keyboard changes

## Variants

- **shape**: rect, round
- **aspect**: 1, 16/9, 3/1 (cover), free

## States

- loading (the picture's shape held, no surround yet)
- ready
- moving (thirds shown)
- zoomed
- rotated
- failed to load (says so)
- disabled
- A free-crop corner keeps its pointer origin across renders, so consecutive drag moves follow the pointer without jumping.

## Keyboard

- Tab reaches the stage: ← → ↑ ↓ move the picture (Shift: ten times as far), + and − zoom, R turns it a quarter, 0 resets
- Tab then reaches the zoom slider, Rotate and Reset
- With a free aspect each corner handle is a stop: the arrow keys resize the window from that corner

## Motion

Dragging, a pinch and the wheel follow the hand at once. The zoom slider eases the picture to each step (critically damped), Rotate turns it a quarter on the same ease, and Reset settles it back to fill the window. Thirds lines fade in while it moves and out a moment after. The picture never leaves the window uncovered: a drag past the edge stops at the edge. Reduced motion: every change is instant.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src` (required) | `string` | — |  |
| `alt` | `string` | — | What the picture shows; names the stage for assistive tech. |
| `aspect` | `number \| "free"` | — | Width over height of the window. Default 1. |
| `shape` | `"rect" \| "round"` | — | round draws a circle (aspect 1). |
| `value / defaultValue / onValueChange` | `CropValue` | — |  |
| `onValueCommit` | `(value: CropValue) => void` | — | When a drag, pinch, key or slider move ends. |
| `minZoom / maxZoom` | `number` | — | Default 1 and 4. |
| `toolbar` | `boolean` | — | Show the zoom slider, Rotate and Reset. Default true. |
| `disabled` | `boolean` | — |  |
| `className / classNames / style / ref` | `root` | — |  |

## Built from

- slider
- button

## Dependencies

`lucide-react`, `@radix-ui/react-slider`

## Import

```tsx
import { ImageCropper } from "@/components/image-cropper/image-cropper";
```

## Get it

Image cropper is part of Beamline: 200+ components and 50+ complete screens for React that your coding agent (Claude Code, Codex, Cursor or any MCP client) installs into your app through Beamline's MCP server, as a ready-built package or as plain React source you can change. $49 launch price, one payment, no subscription, lifetime updates, one licence for your whole team. [Get Beamline](https://beamline.io/checkout?pack=complete) · [Connect your agent](https://beamline.io/connect)

## More in Form controls

- [Color Palette](https://beamline.io/components/color-palette): A wheel of preset colours to pick from: twelve hues around the ring, their tints inward, white at the middle; the chosen swatch lifts and carries a check.
- [Rich text editor](https://beamline.io/components/rich-text-editor): A Notion-grade writing surface: slash menu for every block, a formatting toolbar on selection, drag-to-move blocks, nesting, markdown shortcuts, paste…
- [Allocation editor](https://beamline.io/components/allocation-editor): Parts of a fixed whole edited as transfers: an ordered strip whose boundaries drag or step between neighbours and a roster of exact amounts where typing…
- [Radio cards](https://beamline.io/components/radio-cards): One choice among rich options as cards with optional media, icon, detail and a figure; one selection ring follows the stable choice.
- [Calendar](https://beamline.io/components/calendar): Month grids for picking a day or a range: a real grid with arrows by day and week, Page keys by month, closed days, today's dot, and a range span that…
- [Availability rule editor](https://beamline.io/components/availability-rule-editor): When someone (or something) can be booked: hours for each day of the week, one or more ranges a day, a day turned off, a day's hours copied to the others…
- [Recurrence editor](https://beamline.io/components/recurrence-editor): How something repeats, set in plain controls and said back in a sentence: every N days, weeks, months or years; which weekdays; in a month, on a date or…
- [Signature pad](https://beamline.io/components/signature-pad): A pad for a drawn signature whose ink follows a stylus's pressure (and thins with speed under a mouse or finger); undo, replay, PNG or SVG export, and…
- [Input Dissolve](https://beamline.io/components/input-dissolve): A one-line field whose text breaks into specks and drifts off once it is sent, last letter first; the field is empty and ready again.
- [Password field](https://beamline.io/components/password-field): A password field with a reveal control, and a strength meter when a password is being created.
- [Card field](https://beamline.io/components/card-field): A payment card in one field: the number groups as it is typed and names its network, the expiry and security code follow on their own as each part…
- [File drop zone](https://beamline.io/components/file-dropzone): A generous target for files: drop or choose, each checked against type, size and count with the reason when turned away; uploads show progress and can be…
- [Slider](https://beamline.io/components/slider): A value or range on a known scale: the thumb grows under the finger and shows its value while dragged or focused; marks, end icons and a value readout.
- [Rating](https://beamline.io/components/rating): A score on a small scale: stars that fill as you point (halves too) and light one after another when chosen, with the word for the score beside them…
- [Date range picker](https://beamline.io/components/date-range-picker): A reporting range: presets on one side and two months on the other (one on a phone); the trigger names the preset in use, and the footer counts the days.
- [OTP input](https://beamline.io/components/otp-input): A verification code in separate boxes backed by one real field, so paste, SMS autofill and Backspace work; optional groups like 123–456.
- [Segmented control](https://beamline.io/components/segmented-control): Two to five views or ranges of the same content (1D / 1W / 1M, List / Board): a radio group whose raised thumb slides to the choice.
- [Colour picker](https://beamline.io/components/color-picker): A swatch that opens a picker: saturation-brightness plane, hue strip, HEX/RGB/HSL/OKLCH value to type or copy, the screen eyedropper where available…
- [Chip group](https://beamline.io/components/chip-group): Quick filters as chips: a chosen chip fills and grows a check, counts show what each would return, and extra chips fold behind “+N”.
- [Shortcut recorder](https://beamline.io/components/shortcut-recorder): Lets people set their own shortcut: press the keys, see them as keycaps; a clash or a browser-kept shortcut asks first. ShortcutCheatsheet lists every…
- [Mention input](https://beamline.io/components/mention-input): A composer where @people and #channels become single tokens with suggestions at the caret; the value keeps the text and where each mention sits.
- [Tag input](https://beamline.io/components/tag-input): Short free-form values as tags: Enter, comma or Tab adds, a pasted list adds them all, Backspace twice removes the last; duplicates and invalid values…
- [Multi-select](https://beamline.io/components/multi-select): Several values from a known list as removable chips in the field; the list has a search field (for long lists), checkable rows and a count with Clear.
- [Tree select](https://beamline.io/components/tree-select): A field that picks from a tree: departments and teams, categories and subcategories, folders, regions and cities; the list opens as an indented tree…
- [Combobox](https://beamline.io/components/combobox): One value from a long list found by typing (time zones, countries, customers): ranked matches with the match emphasised, keywords, optional group…
- [Phone input](https://beamline.io/components/phone-input): A phone number with its country: searchable picker with country and dialling codes, “+44…” switches the country, the number groups as typed, and the…
- [Date picker](https://beamline.io/components/date-picker): One date in a form: a field that opens the month grid under it with focus inside, picks and closes; Today and Clear below, optional clear button.
- [Time picker](https://beamline.io/components/time-picker): A time of day as hour and minute segments, typed or stepped, 12- or 24-hour; the clock opens a list of times at the step.
- [Number field](https://beamline.io/components/number-field): A bounded number with − and +: arrows and Page keys step, typing is read in the locale and clamped on leaving, limits can be explained, and the label can…
- [Inline edit](https://beamline.io/components/inline-edit): Text that becomes a field in the same place: Enter (or ⌘Enter when multiline) saves, Escape cancels, leaving saves; saving shows progress and a refusal…
- [Search field](https://beamline.io/components/search-field): The search entry point: magnifier, clear button, Escape to clear, a shortcut hint and an optional live border beam.
- [Switch](https://beamline.io/components/switch): A setting that applies at once: a thumb that slides on a spring and stretches under the finger, with an optional label before or after.
- [Form](https://beamline.io/components/form): Validation wiring for react-hook-form (and zod) on the system's own fields: each field already links its label, help and error, so FormField hands over…
- [Select](https://beamline.io/components/select): One choice from a short known list, in the same frame as every text field: label, help, error, option groups and details.
- [Toggle group](https://beamline.io/components/toggle-group): Pressable toggles where one or several can be on: alignment, bold and italic, view options; bare for toolbars or framed.
- [Input](https://beamline.io/components/input): A single-line text field with its label, help and error wired for assistive tech, three sizes and adornments.
- [Checkbox](https://beamline.io/components/checkbox): A yes/no choice with an optional label and help, including the mixed state for select-all; the check draws itself in.
- [Radio group](https://beamline.io/components/radio-group): One choice from a short visible set, each option with an optional description, vertical or in a row.
- [Textarea](https://beamline.io/components/textarea): Multi-line plain text that grows with what is typed up to a limit, with an optional character count.
- [Label](https://beamline.io/components/label): The text label tied to a form control, with a required marker that screen readers announce.