> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ImageInput

> Image selection, preview, and upload actions with application-owned storage.

export const StoryEmbed = ({storyId, title, height = 240}) => <>
    <Tabs>
      <Tab title="Light">
        <iframe title={`${title} (light)`} src={`https://storybook.twenty.com/iframe.html?id=${storyId}&viewMode=story&globals=colorScheme:light`} width="100%" height={height} loading="lazy" style={{
  border: 0
}} />
      </Tab>
      <Tab title="Dark">
        <iframe title={`${title} (dark)`} src={`https://storybook.twenty.com/iframe.html?id=${storyId}&viewMode=story&globals=colorScheme:dark`} width="100%" height={height} loading="lazy" style={{
  border: 0
}} />
      </Tab>
    </Tabs>
    <a href={`https://storybook.twenty.com/?path=/story/${storyId}`}>
      Open in Storybook
    </a>
  </>;

`ImageInput` combines an image preview, a native file picker, and upload, remove, or abort actions. Pass a resolved image URL as `src`. Your application validates files, uploads them, saves the resulting URL, and supplies instructions and errors.

<StoryEmbed storyId="ui-input-imageinput--with-helper-text" title="Image input with an existing image" height={180} />

```tsx theme={null}
import { ImageInput, type ImageInputProps } from 'twenty-ui/components';

export const WorkspaceImage = ({
  src,
  onUpload,
  onRemove,
}: Pick<ImageInputProps, 'src' | 'onUpload' | 'onRemove'>) => (
  <ImageInput
    src={src}
    onUpload={onUpload}
    onRemove={onRemove}
    helperText="Choose a square image for your workspace."
  />
);
```

## Selection and preview

The preview and Upload button open the same native file picker. `onUpload` receives the selected `File`. 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.

Native file selection and usable `File` contents are not supported in the current front-component sandbox. React and Preact renderer coverage includes previews, action callbacks, and state. Use an ordinary React host for the complete native selection flow.

The `accept` prop 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.

## 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 `onUpload`. Removal requires both `onRemove` and a nonempty `src`.

<StoryEmbed storyId="ui-input-imageinput--uploading" title="Image upload with an abort action" height={180} />

## 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.

`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={200} />

Native div attributes, `className`, `style`, and `ref` apply to the root. Use `render` for root composition and keep that root non-interactive, since the module already contains buttons. Use `dir="rtl"` for right-to-left layout.

## Props

<ParamField body="abortLabel" type="string" default="Abort">
  Label for the Abort action.
</ParamField>

<ParamField body="accept" type="string" default="image/*">
  Native file picker filter. Defaults to image/\*. The application validates the selected file.
</ParamField>

<ParamField body="className" type="string">
  Class applied to the root element.
</ParamField>

<ParamField body="disabled" type="boolean" default="false">
  Disables file selection, removal, and abort actions.
</ParamField>

<ParamField body="errorMessage" type="string | null">
  Application error, displayed as an alert and associated with the selection controls.
</ParamField>

<ParamField body="helperText" type="string">
  Application instructions, associated with the selection controls.
</ParamField>

<ParamField body="isUploading" type="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.
</ParamField>

<ParamField body="onAbort" type="(() => void)">
  Shows an abort action while uploading. It can cancel the first upload before a src exists.
</ParamField>

<ParamField body="onRemove" type="(() => void)">
  Requests removal of the current image. Removal is disabled without this callback or a nonempty src.
</ParamField>

<ParamField body="onUpload" type="((file: File) => void)">
  Receives the selected File. Empty and canceled selections do not call it. Selection is disabled when omitted.
</ParamField>

<ParamField body="ref" type="Ref<HTMLDivElement>">
  Ref to the root element.
</ParamField>

<ParamField body="removeLabel" type="string" default="Remove">
  Label for the Remove action.
</ParamField>

<ParamField body="render" type="ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>">
  Custom root element or render function. Keep a non-interactive root.
</ParamField>

<ParamField body="src" type="string | null">
  Resolved image URL. Empty or failed images show the image placeholder.
</ParamField>

<ParamField body="style" type="CSSProperties">
  Inline style applied to the root element.
</ParamField>

<ParamField body="uploadLabel" type="string" default="Upload">
  Label for the preview and Upload action.
</ParamField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.