---
title: "Images"
slug: "images"
category: "Mini Widgets"
hosts: "react"
reactComponent: "ArcWidgetImage"
reactTier: "mini"
reactSince: "0.1.0-alpha.7"
locale: "es"
---

# Image en React

Muestra una foto, un logotipo o un avatar dentro de tablas, tarjetas, Kanban y layouts. La caja mantiene su forma mientras la imagen carga, y un marcador de posición ocupa su lugar cuando no hay imagen o la URL falla.

Referencia para `@arcrider/arcwidgets-react@0.1.0-alpha.7`. [Instalación](/docs/react/intro/setup-react) · [Todos los componentes](/docs/react/intro/react-components).

## AI Defaults (read first)

- `value` es la URL de la imagen o una data URL (`data:image/png;base64,…`).
- Define `alt` en imágenes con contenido. Sin `alt` se usa `title`; sin ninguno de los dos la imagen se considera decorativa.
- Sin `width` / `height` la imagen se muestra en su tamaño natural, nunca más ancha que su contenedor.
- Para miniaturas y avatares define `width` y `height` y usa `objectFit: 'cover'`. El valor por defecto `contain` muestra la imagen completa.
- Perfiles sin foto: define `initials` (p. ej. `'JJ'`) y nombra a la persona en `alt`. Las letras se muestran mientras no hay imagen o falla la carga, nunca mientras carga.
- Para tarjetas usa `aspectRatio` (p. ej. `'16/9'`) en lugar de una `height` fija: la caja ocupa todo el ancho y mantiene su forma antes de que cargue la imagen.
- Las esquinas redondeadas y las líneas van en `border` (`radius: '50%'` para un círculo), no en `styles`.
- Las imágenes cargan cuando entran en pantalla. Usa `loading: 'eager'` solo para la primera imagen visible de una página.

## Ejemplo completo

```tsx
import {
  ArcWidgetImage,
  ArcWidgetLayout,
  ArcWidgetText,
} from '@arcrider/arcwidgets-react';

// Generated landscapes in different sizes keep the example offline.
const photo = (width: number, height: number, color: string) =>
  `data:image/svg+xml,${encodeURIComponent(
    `<svg xmlns='http://www.w3.org/2000/svg' width='${width}' height='${height}'>` +
      `<rect width='${width}' height='${height}' fill='${color}'/>` +
      `<path d='M0 ${height} L${width * 0.35} ${height * 0.45} L${width * 0.6} ${height * 0.75} L${width} ${height * 0.4} L${width} ${height} Z' fill='#18181B' fill-opacity='0.5'/>` +
      '</svg>',
  )}`;

const projects = [
  { title: 'North site', image: photo(1600, 900, '#38BDF8') },
  { title: 'Harbor depot', image: photo(800, 800, '#A78BFA') },
  { title: 'City office', image: photo(700, 1000, '#FB923C') },
];

export default function Example() {
  // The images have different shapes, the cards do not: `aspectRatio` fixes the box
  // to 16:9 at the full card width before anything loads, and `cover` fills it.
  return (
    <ArcWidgetLayout
      data={{
        direction: 'horizontal',
        alignY: 'top',
        width: '100%',
        height: '100%',
        gap: '16px',
        paddingX: '24px',
        paddingY: '24px',
        backgroundColor: '#F4F4F5',
        blocks: projects.map((project) => ({
          width: 'fraction',
          value: (
            <ArcWidgetLayout
              data={{
                direction: 'vertical',
                gap: '10px',
                paddingX: '10px',
                paddingY: '10px',
                backgroundColor: '#FFFFFF',
                border: { color: '#E4E4E7', radius: '12px' },
                blocks: [
                  {
                    value: (
                      <ArcWidgetImage
                        data={{
                          value: project.image,
                          alt: project.title,
                          aspectRatio: '16/9',
                          objectFit: 'cover',
                          border: { radius: '8px' },
                        }}
                      />
                    ),
                  },
                  {
                    value: (
                      <ArcWidgetText
                        data={{ value: project.title, fontSize: '14px', fontWeight: 600 }}
                      />
                    ),
                  },
                ],
              }}
            />
          ),
        })),
      }}
    />
  );
}
```

## Prueba estas funciones

Cada ejemplo define solo los valores que forman la variante.

### Tamaño natural

Solo se definen `value` y `alt`. La imagen tiene el tamaño de su archivo, como máximo el ancho de su contenedor.

```tsx
import { ArcWidgetImage, ArcWidgetLayout } from '@arcrider/arcwidgets-react';

// A generated landscape keeps the example offline. Any image URL or data URL works.
const photo = `data:image/svg+xml,${encodeURIComponent(
  "<svg xmlns='http://www.w3.org/2000/svg' width='1200' height='800'>" +
    "<rect width='1200' height='800' fill='#6366F1'/>" +
    "<circle cx='860' cy='240' r='96' fill='#FDE68A'/>" +
    "<path d='M0 800 L420 360 L720 600 L940 460 L1200 800 Z' fill='#18181B' fill-opacity='0.55'/>" +
    '</svg>',
)}`;

export default function Example() {
  // Only the source is set on the image. It shows at its natural size,
  // never wider than its container, so it shrinks with the window.
  return (
    <ArcWidgetLayout
      data={{
        direction: 'vertical',
        alignX: 'center',
        alignY: 'center',
        width: '100%',
        height: '100%',
        paddingX: '24px',
        paddingY: '24px',
        backgroundColor: '#F8FAFC',
        border: { radius: '12px' },
        blocks: [
          {
            width: 'fraction',
            alignX: 'center',
            value: (
              <ArcWidgetImage
                data={{ value: photo, alt: 'Mountain landscape' }}
              />
            ),
          },
        ],
      }}
    />
  );
}
```

### Ajustar y recortar

El mismo retrato en la misma caja. `objectFit` decide cómo la llena, `objectPosition` qué parte sigue visible.

```tsx
import {
  ArcWidgetImage,
  ArcWidgetLayout,
  ArcWidgetText,
} from '@arcrider/arcwidgets-react';

// A generated portrait photo keeps the example offline.
const photo = `data:image/svg+xml,${encodeURIComponent(
  "<svg xmlns='http://www.w3.org/2000/svg' width='600' height='900'>" +
    "<rect width='600' height='900' fill='#F472B6'/>" +
    "<circle cx='300' cy='200' r='90' fill='#FDE68A'/>" +
    "<path d='M0 900 L180 520 L360 760 L460 620 L600 900 Z' fill='#18181B' fill-opacity='0.55'/>" +
    '</svg>',
)}`;

// The same portrait in the same 200 x 140 box. `objectFit` decides how it fills the box,
// `objectPosition` which part stays visible when it is cropped.
const variants = [
  { label: 'contain (default)', data: {} },
  { label: 'cover', data: { objectFit: 'cover' as const } },
  { label: 'cover, top', data: { objectFit: 'cover' as const, objectPosition: 'top' } },
];

export default function Example() {
  return (
    <ArcWidgetLayout
      data={{
        direction: 'horizontal',
        alignX: 'center',
        alignY: 'center',
        width: '100%',
        height: '100%',
        gap: '24px',
        paddingX: '24px',
        backgroundColor: '#F8FAFC',
        border: { radius: '12px' },
        blocks: variants.map((variant) => ({
          width: 'auto',
          value: (
            <ArcWidgetLayout
              data={{
                direction: 'vertical',
                alignX: 'center',
                gap: '8px',
                blocks: [
                  {
                    width: 'auto',
                    value: (
                      <ArcWidgetImage
                        data={{
                          value: photo,
                          alt: 'Portrait photo',
                          width: '200px',
                          height: '140px',
                          backgroundColor: '#E4E4E7',
                          border: { radius: '10px' },
                          ...variant.data,
                        }}
                      />
                    ),
                  },
                  {
                    width: 'auto',
                    value: (
                      <ArcWidgetText
                        data={{ value: variant.label, fontSize: '13px', fontColor: '#52525B' }}
                      />
                    ),
                  },
                ],
              }}
            />
          ),
        })),
      }}
    />
  );
}
```

### Avatares

Una caja cuadrada con `border.radius: '50%'` y `objectFit: 'cover'` da un avatar redondo. Para personas sin foto, `initials` aparecen en lugar del icono del marcador; las letras crecen con la caja.

```tsx
import { ArcWidgetImage, ArcWidgetLayout } from '@arcrider/arcwidgets-react';

// Generated square portraits keep the example offline.
const portrait = (color: string) =>
  `data:image/svg+xml,${encodeURIComponent(
    "<svg xmlns='http://www.w3.org/2000/svg' width='256' height='256'>" +
      `<rect width='256' height='256' fill='${color}'/>` +
      "<circle cx='128' cy='104' r='48' fill='#FFFFFF' fill-opacity='0.9'/>" +
      "<path d='M40 256 C40 190 216 190 216 256 Z' fill='#FFFFFF' fill-opacity='0.9'/>" +
      '</svg>',
  )}`;

// `photo` is missing for some people: their `initials` take the place of the image.
const team = [
  { name: 'Alex Morgan', initials: 'AM', color: '#6366F1', photo: true },
  { name: 'Sam Lee', initials: 'SL', color: '#0EA5E9', photo: true },
  { name: 'Robin Diaz', initials: 'RD', color: '#F59E0B', photo: false },
  { name: 'Kim Novak', initials: 'KN', color: '#10B981', photo: false },
];

export default function Example() {
  // A square box with `radius: '50%'` gives a circle; `cover` fills it without distortion.
  // `title` names each person on hover; `alt` names them for screen readers.
  // Without a photo, or when it fails to load, `initials` show instead of the placeholder icon.
  return (
    <ArcWidgetLayout
      data={{
        direction: 'horizontal',
        alignX: 'center',
        alignY: 'center',
        width: '100%',
        height: '100%',
        gap: '8px',
        backgroundColor: '#F8FAFC',
        border: { radius: '12px' },
        blocks: team.map((member) => ({
          width: 'auto',
          value: (
            <ArcWidgetImage
              data={{
                value: member.photo ? portrait(member.color) : undefined,
                alt: member.name,
                title: member.name,
                initials: member.initials,
                backgroundColor: '#E4E4E7',
                width: '48px',
                height: '48px',
                objectFit: 'cover',
                border: { color: '#E4E4E7', radius: '50%' },
              }}
            />
          ),
        })),
      }}
    />
  );
}
```

### Marcador de posición

Sin `value`, o cuando la URL no carga, la caja mantiene su tamaño y muestra un icono de marcador.

```tsx
import {
  ArcWidgetImage,
  ArcWidgetLayout,
  ArcWidgetText,
} from '@arcrider/arcwidgets-react';

// Without `value`, or when the URL fails to load, the box keeps its size
// and shows a placeholder icon instead of a broken-image symbol.
const cases = [
  { label: 'No image yet', value: '' },
  { label: 'URL fails to load', value: 'https://invalid.example/missing.jpg' },
];

export default function Example() {
  return (
    <ArcWidgetLayout
      data={{
        direction: 'horizontal',
        alignX: 'center',
        alignY: 'center',
        width: '100%',
        height: '100%',
        gap: '24px',
        backgroundColor: '#F8FAFC',
        border: { radius: '12px' },
        blocks: cases.map((item) => ({
          width: 'auto',
          value: (
            <ArcWidgetLayout
              data={{
                direction: 'vertical',
                alignX: 'center',
                gap: '8px',
                blocks: [
                  {
                    width: 'auto',
                    value: (
                      <ArcWidgetImage
                        data={{
                          value: item.value,
                          alt: 'Product photo',
                          width: '120px',
                          height: '120px',
                          border: { radius: '12px' },
                        }}
                      />
                    ),
                  },
                  {
                    width: 'auto',
                    value: (
                      <ArcWidgetText
                        data={{ value: item.label, fontSize: '13px', fontColor: '#52525B' }}
                      />
                    ),
                  },
                ],
              }}
            />
          ),
        })),
      }}
    />
  );
}
```

## Props del componente

### id

ID de DOM opcional. No es necesario para el uso normal; se genera automáticamente si se omite.

### data

Configuración de tipo `ArcWidgetImageData`. Pasa los cambios como objetos nuevos.

### onAction

Respaldo opcional `(type: string, ...args: unknown[]) => unknown`. Image no emite eventos propios; para reaccionar a clics colócala dentro de un Button, un bloque de Grid con `clickable` o un bloque de Layout. Detalles: [Estado y eventos](/docs/react/patterns/react-state-events).

## Configuración

Los siguientes campos van en `data`. Los tamaños se indican como cadenas.

### value

URL de la imagen o data URL. Sin valor se muestra el marcador de posición.

Tipo: `string`.

### alt

Texto alternativo para lectores de pantalla. Por defecto: `title`. Deja ambos vacíos en imágenes puramente decorativas.

Tipo: `string`.

### title

Tooltip al pasar el ratón.

Tipo: `string`.

### width

Ancho de la caja, p. ej. `"80px"` o `"100%"`. Por defecto: el ancho de la imagen, como máximo el del contenedor.

Tipo: `string`.

### height

Alto de la caja, p. ej. `"80px"`. Por defecto: sigue a la imagen.

Tipo: `string`.

### aspectRatio

Proporción ancho-alto de la caja, p. ej. `"16/9"` o `"1"`. La caja toma `width` (por defecto: todo el ancho) y su alto sigue la proporción. Si `width` y `height` están definidos, la proporción se ignora.

Tipo: `string`.

### objectFit

Cómo llena la imagen una caja con tamaño. `contain` la muestra completa, `cover` llena la caja y recorta, `fill` estira, `none` mantiene el tamaño original, `scale-down` usa el menor entre `none` y `contain`. Por defecto: `contain`.

Tipo: `'contain' | 'cover' | 'fill' | 'none' | 'scale-down'`.

### objectPosition

Qué parte de la imagen sigue visible cuando se recorta o es menor que la caja, p. ej. `"top"` o `"50% 20%"`. Por defecto: `center`.

Tipo: `string`.

### backgroundColor

Fondo de la caja, visible alrededor de una imagen `contain` y detrás de píxeles transparentes. Por defecto: transparente. Mientras carga y en el marcador la caja es gris claro, salvo que definas este valor.

Tipo: `string`.

### initials

Etiqueta corta que se muestra en lugar del icono del marcador mientras no hay imagen o falla la carga, p. ej. `'JJ'` para un perfil. Se muestra en mayúsculas, como máximo tres caracteres, ajustada al tamaño de la caja. Nombra a la persona en `alt` para los lectores de pantalla.

Tipo: `string`.

### fontColor

Color de las `initials`. Por defecto: gris oscuro.

Tipo: `string`.

### border

Línea y radio de las esquinas de la caja: `color`, `width`, `style`, `radius` y `sides`. La línea aparece en cuanto se define `color`, `width`, `style` o `sides`; `radius` solo redondea las esquinas y recorta la imagen.

Tipo: `ArcWidgetImageBorder`.

### loading

`lazy` carga la imagen cuando entra en pantalla, `eager` de inmediato. Por defecto: `lazy`.

Tipo: `'lazy' | 'eager'`.

### styles

Declaraciones CSS que se aplican al final sobre la caja, p. ej. `'opacity: 0.6'`.

Tipo: `string`.

## Comportamiento y límites

- El widget renderiza un elemento `<img>` real: el navegador lo decodifica fuera del hilo principal, lo carga bajo demanda y lee `alt` a los lectores de pantalla.
- Una imagen que no carga muestra el marcador de posición en lugar del símbolo de imagen rota del navegador. La caja mantiene el tamaño definido; sin tamaño el marcador mide `48px`.
- `initials` sustituyen el icono del marcador solo mientras no hay imagen o no se pudo cargar. Mientras carga, la caja sigue en gris. El tamaño del texto sigue a la caja; con `--arc-image-initials-size` (p. ej. `14px`) en la imagen o en un elemento padre puedes fijarlo.
- Los colores del marcador siguen las propiedades CSS `--arc-image-placeholder-bg`, `--arc-image-placeholder-color` y `--arc-image-placeholder-size`. Defínelas en un elemento padre para todas las imágenes a la vez.
- Image va en slots de contenido como `blocks[].value` o celdas de tabla. No tiene callback de clic propio.

## Tipos de datos

El paquete exporta los siguientes tipos del widget. También están disponibles tipos compartidos como `ArcReactWidgetProps`. Los objetos de configuración son cerrados, así que una clave mal escrita o no soportada es un error de tipos.

```typescript
export interface ArcWidgetImageBorder {
	color?: string;
	width?: string;
	style?: 'solid' | 'dashed' | 'dotted' | 'double';
	radius?: string;
	sides?: Array<'top' | 'right' | 'bottom' | 'left'>;
}

export interface ArcWidgetImageData {
	value?: string;
	alt?: string;
	title?: string;
	width?: string;
	height?: string;
	aspectRatio?: string;
	objectFit?: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down';
	objectPosition?: string;
	backgroundColor?: string;
	initials?: string;
	fontColor?: string;
	border?: ArcWidgetImageBorder;
	loading?: 'lazy' | 'eager';
	styles?: string;
}

export interface ArcWidgetImageProps extends ArcReactWidgetProps<ArcWidgetImageData> {}
```
