---
title: "Custom Grid"
slug: "custom-grid"
category: "Widgets"
hosts: "react"
reactComponent: "ArcWidgetGrid"
reactTier: "mini"
reactSince: "0.1.0-alpha.7"
locale: "es"
---

# Grid en React

Organiza el contenido en filas y columnas a la vez: tarjetas, mosaicos de KPI y dashboards. Sin un número de columnas, el Grid llena la fila con tantas columnas como permita el ancho, así que se adapta a la pantalla sin breakpoints. Usa Arc Layout para una sola dirección (una fila o una columna) y para el marco de la página; usa el Grid cuando el contenido necesita ambas dimensiones.

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)

- Sin `columns`, el Grid llena la fila con columnas de al menos `columnWidth` (por defecto `200px`). Con `columns` fijas un número exacto.
- `gap` es el espacio entre filas y columnas. Por defecto: `10px`.
- `columnSpan` y `rowSpan` en un bloque crean mosaicos anchos o altos. Con `columns` fijo, `columnSpan` se limita a ese número.
- El Grid tiene `height: 'auto'` por defecto y mide lo que mide su contenido. Define una `height` solo si debe llenar un marco.
- Define una sola vez el aspecto común de todos los mosaicos con `blockDefaults` y dibuja los contornos con `border`, no con `styles`.
- Coloca los widgets en `blocks[].value`. No añadas `div` envoltorios para el Grid; el Grid dibuja las pistas.
- Solo los bloques con `clickable: true` reaccionan a los clics. Llaman a `onBlockClick` con su índice.

## Ejemplo completo

```tsx
import { useState } from 'react';
import {
  ArcWidgetBadge,
  ArcWidgetGrid,
  ArcWidgetText,
} from '@arcrider/arcwidgets-react';

export default function Example() {
  const [selected, setSelected] = useState('none');
  const ids = ['revenue', 'orders', 'chart', 'inbox'];

  // `columnSpan` and `rowSpan` make a block wider or taller than one cell.
  // The chart block takes two columns and two rows; the neighbours flow around it.
  return (
    <ArcWidgetGrid
      onBlockClick={(index) => setSelected(ids[index] ?? 'none')}
      data={{
        columns: 4,
        gap: '12px',
        paddingX: '16px',
        paddingY: '16px',
        backgroundColor: '#F4F4F5',
        blockDefaults: {
          clickable: true,
          paddingX: '16px',
          paddingY: '16px',
          backgroundColor: '#FFFFFF',
          border: { color: '#D4D4D8', radius: '12px' },
        },
        blocks: [
          {
            blockId: 'revenue',
            value: <ArcWidgetText data={{ value: 'Revenue EUR 24,300', fontWeight: '700' }} />,
          },
          {
            blockId: 'orders',
            value: <ArcWidgetText data={{ value: 'Orders 128', fontWeight: '700' }} />,
          },
          {
            blockId: 'chart',
            columnSpan: 2,
            rowSpan: 2,
            alignX: 'center',
            alignY: 'center',
            value: 'Chart area (2 x 2)',
          },
          {
            blockId: 'inbox',
            columnSpan: 2,
            value: (
              <ArcWidgetBadge
                data={{
                  value: `Selected: ${selected}`,
                  singleColor: '#3f3f46',
                  borderRadius: '6px',
                  paddingX: '8px',
                  paddingY: '4px',
                }}
              />
            ),
          },
        ],
      }}
    />
  );
}
```

## Props del componente

### id

DOM id opcional. No hace falta en el uso normal; se genera automáticamente si falta.

### data

Configuración de tipo `ArcWidgetGridData`. Pasa los cambios como objetos nuevos; mantén los datos de negocio y la selección en el estado de React.

### onAction

Fallback opcional `(type: string, ...args: unknown[]) => unknown`. El callback específico tiene prioridad. Detalles: [Estado y eventos](/docs/react/patterns/react-state-events).

### onBlockClick

Se dispara al hacer clic en un bloque `clickable`. `blockIndex` es el índice de base cero en `data.blocks`.

```typescript
onBlockClick?: (blockIndex: number) => void;
```

## Configuración

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

### columns

Número de columnas, p. ej. `3`. Si se omite (o `'auto-fill'`), se usan tantas columnas como permita el ancho. `'auto-fit'` también se ajusta al ancho, pero estira las celdas cuando hay pocos bloques. Por defecto: `'auto-fill'`.

Tipo: `number | 'auto-fill' | 'auto-fit' | (string & {})`.

### columnWidth

Ancho mínimo de una columna, p. ej. `"280px"`. Las columnas crecen por igual hasta llenar la fila. Por defecto: `200px`. Con un `columns` fijo y sin `columnWidth`, las columnas se reparten el ancho y se estrechan libremente en pantallas estrechas.

Tipo: `string`.

### gap

Espacio entre bloques, igual para filas y columnas. Por defecto: `10px`.

Tipo: `string`.

### width

Ancho del Grid como CSS. Por defecto: `100%`.

Tipo: `string`.

### height

Altura del Grid como CSS. Usa un valor definido cuando el Grid llena un marco y `'auto'` para grids del tamaño de su contenido. Por defecto: `auto`.

Tipo: `string`.

### paddingX

Espaciado interior a izquierda y derecha.

Tipo: `string`.

### paddingY

Espaciado interior arriba y abajo.

Tipo: `string`.

### backgroundColor

Color de fondo del Grid.

Tipo: `string`.

### border

Línea y radio de esquina del contenedor del Grid: `color`, `width`, `style`, `radius` y `sides`. La línea se dibuja en cuanto se define `color`, `width`, `style` o `sides`; `radius` por sí solo solo redondea las esquinas. Los bloques usan el mismo objeto `border`.

Tipo: `ArcWidgetGridBorder`.

### blockDefaults

Valores que cada bloque toma mientras no defina uno propio, p. ej. `{ paddingX: '16px', backgroundColor: '#FFFFFF', border: { radius: '12px' } }`. Un valor definido en el bloque sustituye al predeterminado por completo, también en `border`. `value` y `blockId` nunca se toman de los valores predeterminados.

Tipo: `Omit<ArcWidgetGridBlock, 'value' | 'blockId'>`.

### styles

Declaraciones CSS en bruto que se aplican al final al contenedor del Grid, p. ej. `'padding: 8px; color: #333'`.

Tipo: `string`.

### blocks

Celdas en orden de lectura. Cada bloque tiene su propio tamaño, extensiones, alineación (`alignX`, `alignY`), colores, `styles` y contenido en `value`; consulta `ArcWidgetGridBlock`.

Tipo: `ArcWidgetGridBlock[]`.

## Comportamiento y límites

- Las filas miden lo que mide su bloque más alto. `rowSpan` hace que un bloque ocupe varias filas y `columnSpan` varias columnas. Los bloques siguientes fluyen alrededor de los bloques con extensión.

- Con `columns` fijo, un `columnSpan` mayor que el número de columnas se limita para que no aparezcan columnas adicionales. En modo auto-fill no hay un número fijo, así que la extensión se aplica tal como se indica.

- Cada bloque es un contenedor flex horizontal. Posiciona su contenido con `blocks[].alignX` (`left`, `center`, `right`; por defecto `left`) y `blocks[].alignY` (`top`, `center`, `bottom`, `stretch`; por defecto `center`). `text-align` en `blocks[].styles` no puede centrar el contenido.

- `blocks[].width` y `blocks[].height` fijan el tamaño del contenido dentro de su área. `'fraction'` llena el área.

- `blocks[].value` admite JSX. Enlaza los eventos de los componentes anidados directamente a sus props de callback.

- Los Grids se pueden anidar. Cada Grid aplica solo sus propios ajustes, nunca los del Grid que lo rodea.

- Para los clics en bloques, `clickable: true` debe estar definido en el bloque. El Grid en sí no tiene callback de clic.

## Tipos de datos

Estos tipos relacionados con el widget se exportan desde el paquete. También están disponibles tipos comunes como `ArcWidgetSlot` y `ArcReactWidgetProps`. Los objetos de configuración son cerrados, por lo que una clave mal escrita o no admitida se notifica como error de tipo.

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

export interface ArcWidgetGridBlock {
	value?: ArcWidgetSlot;
	columnSpan?: number;
	rowSpan?: number;
	width?: string;
	height?: string;
	alignX?: 'left' | 'center' | 'right';
	alignY?: 'top' | 'center' | 'bottom' | 'stretch';
	paddingX?: string;
	paddingY?: string;
	backgroundColor?: string;
	border?: ArcWidgetGridBorder;
	color?: string;
	backgroundImage?: string;
	backgroundSize?: string;
	backgroundPosition?: string;
	lineHeight?: string;
	styles?: string;
	clickable?: boolean;
	blockId?: string;
}

export interface ArcWidgetGridData {
	columns?: number | 'auto-fill' | 'auto-fit' | (string & {});
	columnWidth?: string;
	gap?: string;
	width?: string;
	height?: string;
	paddingX?: string;
	paddingY?: string;
	backgroundColor?: string;
	border?: ArcWidgetGridBorder;
	styles?: string;
	blockDefaults?: Omit<ArcWidgetGridBlock, 'value' | 'blockId'>;
	blocks?: ArcWidgetGridBlock[];
}

export interface ArcWidgetGridProps extends ArcReactWidgetProps<ArcWidgetGridData> {
	onBlockClick?: (blockIndex: number) => void;
}
```
