Mini Widgets
Images
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. <a href="/docs/react/intro/setup-react">Instalación</a> · <a href="/docs/react/intro/react-components">Todos los componentes</a>.
AI Defaults
Ejemplo completo
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 }} /> ), }, ], }} /> ), })), }} /> ); }</code></pre>
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.
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' }} /> ), }, ], }} /> ); }</code></pre>
Ajustar y recortar
El mismo retrato en la misma caja. objectFit decide cómo la llena, objectPosition qué parte sigue visible.
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' }} /> ), }, ], }} /> ), })), }} /> ); }</code></pre>
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.
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%' }, }} /> ), })), }} /> ); }</code></pre>
Marcador de posición
Sin value, o cuando la URL no carga, la caja mantiene su tamaño y muestra un icono de marcador.
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' }} /> ), }, ], }} /> ), })), }} /> ); }</code></pre>
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: <a href="/docs/react/patterns/react-state-events">Estado y eventos</a>.
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.
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> {}</code></pre>