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

> Selección, vista previa y acciones de carga gestionadas por la persona que llama.

## Resumen

`ImageInput` combina una vista previa de imagen, un selector de archivos nativo y acciones de carga, eliminación o cancelación. `onFileSelect` se activa cuando se selecciona un archivo. Su aplicación valida y carga el archivo, gestiona el progreso y la cancelación de la carga, y proporciona la URL de vista previa mediante `src`.

**Light**

[Elige, previsualiza y elimina una imagen (light)](https://storybook.twenty.com/iframe.html?id=ui-input-imageinput--display\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Elige, previsualiza y elimina una imagen (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)

## "Uso"

```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({})}
    />
  );
};
```

El ejemplo mantiene la vista previa actual mientras lee un reemplazo e ignora las lecturas de selecciones eliminadas o sustituidas.

## Selección y vista previa

La vista previa y el botón Cargar abren el mismo selector de archivos nativo. `onFileSelect` recibe el `File` seleccionado; no inicia una carga por sí mismo. Cancelar o devolver una selección vacía deja la imagen actual sin cambios. La entrada de archivo se borra después de la selección para que se pueda seleccionar el mismo archivo de nuevo, y el `File` de la devolución de llamada sigue siendo utilizable.

Los componentes Front admiten la selección nativa y contenido de `File` legible. Los flujos de React y Preact creados con el SDK se verifican en Chromium con activación mediante puntero, Intro y Espacio. El selector se abre únicamente desde un clic de confianza dentro del componente. Las URL de objeto creadas por el worker y asignadas a un `src` de imagen admiten vistas previas.

`accept` usa de forma predeterminada `image/*` y filtra el selector de archivos. Valide los formatos, las dimensiones y el tamaño permitidos en la aplicación. Este selector controlado por callbacks no conserva un archivo para el envío de formularios nativos. Sus botones de acción usan `type="button"`, por lo que no envían un formulario contenedor.

Una imagen vacía o con error muestra un marcador de posición. Cambiar `src` vuelve a intentar la vista previa, incluso después de que no se haya podido cargar una imagen anterior. La eliminación llama a `onRemove`; actualice `src` después de que la aplicación elimine la imagen. La aplicación gestiona las URL de vista previa locales y revoca las URL de objetos creadas por el trabajador cuando ya no son necesarias. El renderizador se encarga de limpiar las URL de vista previa de su host.

## Props de la raíz y de la entrada de archivo

`className`, `style` y `ref` se aplican al div raíz. La ref raíz predeterminada recibe un `HTMLDivElement`; use `inputRef` para la entrada de archivo oculta. Usa `render={<div ... />}` para proporcionar atributos raíz nativos o controladores de eventos. Mantenga esa raíz sin interacción, ya que el módulo ya contiene botones. `dir` se aplica tanto a la raíz como a la entrada de archivo; use `dir="rtl"` para el diseño de derecha a izquierda.

Los atributos de entrada de archivo nativos son props de nivel superior, incluidos `accept`, `capture`, `name`, `id`, `title`, `form`, `required`, atributos accesibles, atributos de datos y controladores de eventos. Se aplican a la entrada oculta. `inputRef` recibe su `HTMLInputElement`. El control siempre usa `type="file"`, acepta un archivo y restablece su valor después de cada selección. `children`, `dangerouslySetInnerHTML`, `type`, `multiple`, `value`, `defaultValue` y `hidden` no se pueden personalizar.

La validación nativa de `required` sigue viendo una entrada vacía después de la selección porque la entrada se restablece. Valide las cargas completadas en su aplicación.

`onChange` recibe el evento de cambio nativo mientras la entrada aún contiene el archivo seleccionado. Después, la entrada se restablece antes de que se active `onFileSelect`. Las props de eventos nativos siguen el contrato de entrada de React. `onAbort` es la acción para cancelar la carga.

## Estados de carga y deshabilitado

`isUploading` marca el elemento raíz como ocupado y hace que la selección y la eliminación no estén disponibles. Los controles que estaban disponibles permanecen enfocables, de modo que el foco del teclado no se pierde cuando comienza una carga. Proporcione `onAbort` para sustituir Cargar por Cancelar durante una carga. Cancelar funciona antes de que exista la primera URL de imagen. La aplicación gestiona la cancelación y vuelve a establecer `isUploading` en `false` cuando termina la carga.

`disabled` deshabilita todas las acciones. La selección requiere `onFileSelect`. La eliminación requiere tanto `onRemove` como un `src` no vacío.

**Light**

[Carga de imagen con una acción de cancelación (light)](https://storybook.twenty.com/iframe.html?id=ui-input-imageinput--uploading\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Carga de imagen con una acción de cancelación (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)

## Etiquetas, instrucciones y errores

Proporcione cadenas localizadas para `uploadLabel`, `removeLabel` y `abortLabel`. Sus valores predeterminados son `Upload`, `Remove` y `Abort`. La etiqueta de carga también da nombre al botón de vista previa y a la entrada de archivo oculta. Los atributos accesibles nativos pueden proporcionar un nombre diferente para la entrada de archivo. `aria-describedby` también describe los botones de selección y se combina con el texto de ayuda y de error de la aplicación.

`helperText` y `errorMessage` pertenecen a la aplicación. Ambos describen los controles de selección, y los errores se anuncian como alertas. No hay límites de archivos ni instrucciones de producto integrados.

**Light**

[Entrada de imagen con instrucciones y un error (light)](https://storybook.twenty.com/iframe.html?id=ui-input-imageinput--with-error\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Entrada de imagen con instrucciones y un error (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)

## Migración

Reemplace `onUpload` por `onFileSelect`. Mantenga `accept` como una prop de nivel superior. La devolución de llamada sigue recibiendo un `File`; mantenga el código existente de validación y carga en su aplicación.

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