The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
---
title: ImageInput
description: Image selection, preview, and caller-owned upload actions.
---
import { PageBanner } from "/snippets/page-banner.mdx"
import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
import ImageInputReference from '/snippets/ui/generated/components/input/image-input.mdx';
## Overview
`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`.
<StoryEmbed
storyId="ui-input-imageinput--display"
title="Choose, preview, and remove an image"
height={140}
/>
## Usage
```tsx
import { useState } from 'react';
import { ImageInput } from 'twenty-ui/components/input';
export const WorkspaceImage = () => {
const [preview, setPreview] = useState<{
src?: string;
reader?: FileReader;
}>({});
return (
<ImageInput
helperText="Choose a square image for your workspace."
src={preview.src}
onFileSelect={(file) => {
const reader = new FileReader();
setPreview((current) => ({ src: current.src, reader }));
reader.onload = () => {
setPreview((current) => {
if (current.reader !== reader) {
return current;
}
return { src: reader.result?.toString() };
});
};
reader.readAsDataURL(file);
}}
onRemove={() => setPreview({})}
/>
);
};
```
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`.
<StoryEmbed
storyId="ui-input-imageinput--uploading"
title="Image upload with an abort action"
height={140}
/>
## 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.
<StoryEmbed
storyId="ui-input-imageinput--with-error"
title="Image input with instructions and an error"
height={160}
/>
## 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.
```tsx
import { ImageInput } from 'twenty-ui/components/input';
export const WorkspaceImageSelector = ({
uploadImage,
}: {
uploadImage: (file: File) => void;
}) => <ImageInput onFileSelect={uploadImage} accept="image/png, image/jpeg" />;
```
## Props
<ImageInputReference />
<PageBanner illustration="page-cover-image" />