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

> Azioni di selezione, anteprima e caricamento delle immagini gestite dal chiamante.

## Panoramica

`ImageInput` combina un'anteprima dell'immagine, un selettore di file nativo e azioni di caricamento, rimozione o annullamento. `onFileSelect` viene attivato quando viene selezionato un file. L'applicazione convalida e carica il file, gestisce l'avanzamento e l'annullamento del caricamento e fornisce l'URL dell'anteprima tramite `src`.

**Light**

[Scegli, visualizza l'anteprima e rimuovi un'immagine (light)](https://storybook.twenty.com/iframe.html?id=ui-input-imageinput--display\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Scegli, visualizza l'anteprima e rimuovi un'immagine (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-imageinput--display\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-imageinput--display)

## Utilizzo

```tsx theme={null}
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({})}
    />
  );
};
```

L'esempio mantiene l'anteprima corrente durante la lettura di un elemento sostitutivo e ignora le letture provenienti da selezioni rimosse o sostituite.

## Selezione e anteprima

L'anteprima e il pulsante Carica aprono lo stesso selettore di file nativo. `onFileSelect` riceve il `File` selezionato; non avvia autonomamente un caricamento. L'annullamento o la restituzione di una selezione vuota lascia invariata l'immagine corrente. L'input file viene svuotato dopo la selezione, quindi è possibile selezionare nuovamente lo stesso file e il `File` del callback resta utilizzabile.

I componenti Front supportano la selezione nativa e contenuti `File` leggibili. I flussi React e Preact creati con l'SDK sono verificati in Chromium con attivazione tramite puntatore, Invio e Spazio. Il selettore si apre solo da un clic attendibile all'interno del componente. Gli URL degli oggetti creati dal worker e assegnati a un'immagine `src` supportano le anteprime.

`accept` è impostato per impostazione predefinita su `image/*` e filtra il selettore di file. Convalida formati, dimensioni e dimensione consentiti nell'applicazione. Questo selettore basato su callback non conserva un file per l'invio nativo del modulo. I relativi pulsanti di azione usano `type="button"`, quindi non inviano un modulo circostante.

Un'immagine vuota o non riuscita mostra un segnaposto. La modifica di `src` riprova l'anteprima, anche dopo che un'immagine precedente non è stata caricata. La rimozione chiama `onRemove`; aggiorna `src` dopo che l'applicazione rimuove l'immagine. L'applicazione gestisce gli URL delle anteprime locali e revoca gli URL oggetto creati dal worker quando non sono più necessari. Il renderer gestisce la pulizia dei propri URL delle anteprime host.

## Proprietà dell'elemento radice e dell'input file

`className`, `style` e `ref` si applicano al div radice. Il ref radice predefinito riceve un `HTMLDivElement`; utilizza `inputRef` per l'input file nascosto. Utilizza `render={<div ... />}` per fornire attributi radice nativi o gestori di eventi. Mantieni l'elemento radice non interattivo, poiché il modulo contiene già pulsanti. `dir` si applica sia all'elemento radice sia all'input file; utilizza `dir="rtl"` per il layout da destra a sinistra.

Gli attributi nativi dell'input file sono proprietà di primo livello, tra cui `accept`, `capture`, `name`, `id`, `title`, `form`, `required`, attributi accessibili, attributi dati e gestori di eventi. Si applicano all'input nascosto. `inputRef` riceve il proprio `HTMLInputElement`. Il controllo utilizza sempre `type="file"`, accetta un file e reimposta il proprio valore dopo ogni selezione. `children`, `dangerouslySetInnerHTML`, `type`, `multiple`, `value`, `defaultValue` e `hidden` non possono essere personalizzati.

La convalida nativa di `required` rileva comunque un input vuoto dopo la selezione, poiché l'input viene reimpostato. Convalida i caricamenti completati nella tua applicazione.

`onChange` riceve l'evento di modifica nativo mentre l'input contiene ancora il file selezionato. L'input viene quindi reimpostato prima che venga attivato `onFileSelect`. Le proprietà degli eventi nativi seguono il contratto degli input di React. `onAbort` è l'azione di annullamento del caricamento.

## Stati di caricamento e disabilitato

`isUploading` contrassegna la radice come occupata e rende selezione e rimozione non disponibili. I controlli che erano disponibili restano attivabili tramite focus, quindi il focus della tastiera non va perso quando inizia un caricamento. Fornisci `onAbort` per sostituire Carica con Annulla durante un caricamento. Annulla funziona prima che esista il primo URL dell'immagine. L'applicazione gestisce l'annullamento e reimposta `isUploading` su `false` al termine del caricamento.

`disabled` disabilita ogni azione. La selezione richiede `onFileSelect`. La rimozione richiede sia `onRemove` sia un `src` non vuoto.

**Light**

[Caricamento immagine con un'azione di annullamento (light)](https://storybook.twenty.com/iframe.html?id=ui-input-imageinput--uploading\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Caricamento immagine con un'azione di annullamento (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-imageinput--uploading\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-imageinput--uploading)

## Etichette, istruzioni ed errori

Fornisci stringhe localizzate per `uploadLabel`, `removeLabel` e `abortLabel`. Per impostazione predefinita sono `Upload`, `Remove` e `Abort`. L'etichetta di caricamento assegna un nome anche al pulsante di anteprima e all'input file nascosto. Gli attributi nativi accessibili possono fornire un nome diverso all'input file. `aria-describedby` descrive anche i pulsanti di selezione e si combina con il testo di supporto e di errore dell'applicazione.

`helperText` e `errorMessage` appartengono all'applicazione. Entrambi descrivono i controlli di selezione e gli errori vengono annunciati come avvisi. Non sono presenti limiti integrati per i file né istruzioni sul prodotto.

**Light**

[Input immagine con istruzioni e un errore (light)](https://storybook.twenty.com/iframe.html?id=ui-input-imageinput--with-error\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Input immagine con istruzioni e un errore (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-imageinput--with-error\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-imageinput--with-error)

## Migrazione

Sostituisci `onUpload` con `onFileSelect`. Mantieni `accept` come proprietà di primo livello. Il callback riceve ancora un `File`; mantieni nell'applicazione il codice di convalida e caricamento esistente.

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

export const WorkspaceImageSelector = ({
  uploadImage,
}: {
  uploadImage: (file: File) => void;
}) => <ImageInput onFileSelect={uploadImage} accept="image/png, image/jpeg" />;
```

## Props

**abortLabel** `string` (default: Abort)

Label for the Abort action.

**accept** `string` (default: image/\*)

Native file picker filter. Defaults to image/\*. The caller validates allowed formats.

**aria-describedby** `string`

Accessible description references for the hidden file input and selection buttons, combined with helperText and errorMessage.

**aria-label** `string`

Accessible name of the hidden file input. Defaults to uploadLabel.

**aria-labelledby** `string`

Accessible name reference for the hidden file input.

**capture** `boolean | "user" | "environment"`

Native device capture hint for the file picker.

**className** `string`

Class applied to the root element.

**dir** `string`

Text direction applied to both the root and hidden file input.

**disabled** `boolean` (default: false)

Disables file selection, removal, and abort actions.

**errorMessage** `string | null`

Application error, displayed as an alert and associated with the selection controls.

**form** `string`

Native form identifier associated with the hidden file input.

**helperText** `string`

Application instructions, associated with the selection controls.

**id** `string`

Native identifier of the hidden file input.

**inputRef** `Ref\<HTMLInputElement\>`

Ref to the hidden single-file HTMLInputElement.

**isUploading** `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.

**name** `string`

Native name of the hidden file input.

**onAbort** `(() =\> void)`

Shows an abort action while uploading. It can cancel the first upload before a src exists.

**onChange** `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.

**onFileSelect** `((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.

**onRemove** `(() =\> void)`

Requests removal of the current image. Removal is disabled without this callback or a nonempty src.

**ref** `Ref\<HTMLDivElement\>`

Ref to the root div element.

**removeLabel** `string` (default: Remove)

Label for the Remove action.

**render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, \{\}\>`

Custom root element or render function. Supply root native attributes here and keep a non-interactive root.

**required** `boolean`

Native file input requirement. The input resets after selection, so the caller validates completed uploads.

**src** `string | null`

Resolved image URL. Empty or failed images show the image placeholder.

**style** `CSSProperties`

Inline style applied to the root element.

**title** `string`

Native title of the hidden file input.

**uploadLabel** `string` (default: Upload)

Label for the preview, Upload action, and hidden file input.


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