Skip to main content
ImageInput combines an image preview, a native file picker, and upload, remove, or abort actions. onFileSelect fires when a file is selected. Your application validates and uploads the file, owns upload progress and cancellation, and supplies the preview URL through src.

Usage

The example keeps the current preview while reading a replacement and ignores reads from removed or superseded selections.

Selection and preview

The preview and Upload button open the same native file picker. onFileSelect receives the selected File; it does not start an upload itself. Canceling or returning an empty selection leaves the current image unchanged. The file input clears after selection so the same file can be selected again, and the callback’s File remains usable. Front components support native selection and readable File contents. The SDK-built React and Preact flows are verified in Chromium with pointer, Enter and Space activation. The picker opens only from a trusted click inside the component. Worker-created object URLs assigned to an image src support previews. accept defaults to image/* and filters the file picker. Validate allowed formats, dimensions, and size in your application. This callback-driven selector does not retain a file for native form submission. Its action buttons use type="button", so they do not submit a surrounding form. An empty or failed image shows a placeholder. Changing src retries the preview, including after an earlier image failed to load. Removal calls onRemove; update src after your application removes the image. The application owns local preview URLs and revokes worker-created object URLs when they are no longer needed. The renderer owns cleanup of its host preview URLs.

Root and file input props

className, style, and ref apply to the root div. The default root ref receives an HTMLDivElement; use inputRef for the hidden file input. Use render={<div ... />} to supply native root attributes or event handlers. Keep that root non-interactive, since the module already contains buttons. dir applies to both the root and file input; use dir="rtl" for right-to-left layout. Native file input attributes are top-level props, including accept, capture, name, id, title, form, required, accessible attributes, data attributes, and event handlers. They apply to the hidden input. inputRef receives its HTMLInputElement. The control always uses type="file", accepts one file, and resets its value after every selection. children, dangerouslySetInnerHTML, type, multiple, value, defaultValue, and hidden cannot be customized. Native required validation still sees an empty input after selection because the input resets. Validate completed uploads in your application. onChange receives the native change event while the input still contains the selected file. The input then resets before onFileSelect fires. Native event props follow React’s input contract. onAbort is the upload abort action.

Uploading and disabled states

isUploading marks the root busy and makes selection and removal unavailable. Controls that were available stay focusable, so keyboard focus is not lost when an upload starts. Supply onAbort to replace Upload with Abort during an upload. Abort works before the first image URL exists. The application owns cancellation and sets isUploading back to false when the upload ends. disabled disables every action. Selection requires onFileSelect. Removal requires both onRemove and a nonempty src.

Labels, instructions, and errors

Supply localized uploadLabel, removeLabel, and abortLabel strings. They default to Upload, Remove, and Abort. The upload label also names the preview button and the hidden file input. Native accessible attributes can provide a different file input name. aria-describedby also describes the selection buttons and combines with the application’s helper and error text. helperText and errorMessage belong to the application. Both describe the selection controls, and errors are announced as alerts. There are no built-in file limits or product instructions.

Migration

Replace onUpload with onFileSelect. Keep accept as a top-level prop. The callback still receives a File; keep existing validation and upload code in your application.

Props

string
default:"Abort"
Label for the Abort action.
string
default:"image/*"
Native file picker filter. Defaults to image/*. The caller validates allowed formats.
string
Accessible description references for the hidden file input and selection buttons, combined with helperText and errorMessage.
string
Accessible name of the hidden file input. Defaults to uploadLabel.
string
Accessible name reference for the hidden file input.
boolean | "user" | "environment"
Native device capture hint for the file picker.
string
Class applied to the root element.
string
Text direction applied to both the root and hidden file input.
boolean
default:"false"
Disables file selection, removal, and abort actions.
string | null
Application error, displayed as an alert and associated with the selection controls.
string
Native form identifier associated with the hidden file input.
string
Application instructions, associated with the selection controls.
string
Native identifier of the hidden file input.
Ref<HTMLInputElement>
Ref to the hidden single-file HTMLInputElement.
boolean
default:"false"
Marks the module busy. Selection and removal controls that would otherwise be enabled stay focusable but unavailable. Shows Abort when onAbort is supplied.
string
Native name of the hidden file input.
(() => void)
Shows an abort action while uploading. It can cancel the first upload before a src exists.
ChangeEventHandler<HTMLInputElement, HTMLInputElement>
Native file input change event, fired while the selected file is present and before the input resets. The input does not retain a file for form submission.
((file: File) => void)
Fires when a file is selected and receives its usable File after the input resets. Empty and canceled selections do not call it. Selection is disabled when omitted. The caller owns validation and uploading.
(() => void)
Requests removal of the current image. Removal is disabled without this callback or a nonempty src.
Ref<HTMLDivElement>
Ref to the root div element.
string
default:"Remove"
Label for the Remove action.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>
Custom root element or render function. Supply root native attributes here and keep a non-interactive root.
boolean
Native file input requirement. The input resets after selection, so the caller validates completed uploads.
string | null
Resolved image URL. Empty or failed images show the image placeholder.
CSSProperties
Inline style applied to the root element.
string
Native title of the hidden file input.
string
default:"Upload"
Label for the preview, Upload action, and hidden file input.