Virtual scroll

Lista virtualizada — 10 mil filas, ~25 nodos del DOM.

Navegadores: Chrome 123+Firefox 121+Safari 17.5+
Nivel: 2
Tamaño comprimido: 4.16 kB
Presupuesto de diseño forzado: 0 ms
Presupuesto de axe: 0
Compatible con SSR: Sí
Contrato publicado: Entorno de pruebas

Zona de pruebas

React

CSS

Tailwind

/* Generic skin for custom core surfaces used by the demo and consumers. */

@layer components {
  [data-uiify-surface] {
    display: grid;
    gap: var(--space-md);
    inline-size: max-content;
    max-inline-size: min(28rem, calc(100vw - 2 * var(--space-lg)));
    padding: var(--space-lg);
    border: var(--border-width) solid var(--border);
    border-radius: var(--radius-xl);
    corner-shape: squircle;
    background-color: var(--card);
    color: var(--card-foreground);
    box-shadow: var(--shadow-popover);
  }

  [data-uiify-surface][popover]:not(:popover-open) {
    display: none;
  }

  @media (prefers-reduced-motion: no-preference) {
    [data-uiify-surface][popover] {
      transition: var(--transition-presence);
    }

    [data-uiify-surface][popover]:not(:popover-open) {
      opacity: 0;
      scale: var(--presence-scale);
    }

    @starting-style {
      [data-uiify-surface][popover]:popover-open {
        opacity: 0;
        scale: var(--presence-scale);
      }
    }
  }
}

import { VirtualScroll } from "@gunkin/uiify";

const items = Array.from({ length: 10000 }, (_, index) => ({
  id: String(index),
  label: "Row " + (index + 1),
}));

export default function Example() {
  return (
    <>
      <VirtualScroll
        className="
          grid gap-md w-max max-w-[min(28rem,calc(100vw_-_2_*_var(--space-lg)))] p-6 border border-border rounded-xl
          [corner-shape:squircle] bg-card text-card-foreground shadow-popover [&[popover]:not(:popover-open)]:hidden
          motion-safe:[&[popover]]:[transition:var(--transition-presence)]
          motion-safe:[&[popover]:not(:popover-open)]:opacity-0
          motion-safe:[&[popover]:not(:popover-open)]:[scale:var(--presence-scale)]
          motion-safe:starting:[&[popover]:popover-open]:opacity-0
          motion-safe:starting:[&[popover]:popover-open]:[scale:var(--presence-scale)]
        "
        height={400}
        items={items}
        renderRow={(item) => <div>{item.label}</div>}
      />
      {/* rowHeight is the item size along the scroll axis — here, each card's width. */}
      <VirtualScroll
        className="
          grid gap-md w-max max-w-[min(28rem,calc(100vw_-_2_*_var(--space-lg)))] p-6 border border-border rounded-xl
          [corner-shape:squircle] bg-card text-card-foreground shadow-popover [&[popover]:not(:popover-open)]:hidden
          motion-safe:[&[popover]]:[transition:var(--transition-presence)]
          motion-safe:[&[popover]:not(:popover-open)]:opacity-0
          motion-safe:[&[popover]:not(:popover-open)]:[scale:var(--presence-scale)]
          motion-safe:starting:[&[popover]:popover-open]:opacity-0
          motion-safe:starting:[&[popover]:popover-open]:[scale:var(--presence-scale)]
        "
        height={120}
        items={items}
        orientation="horizontal"
        rowHeight={144}
        renderRow={(item) => <div>{item.label}</div>}
      />
    </>
  );
}

/* app.css */

@layer reset, ui, app, tokens, base, demo, components, utilities, theme;

@import "@gunkin/uiify/styles/reset";

@import "@gunkin/uiify/components/behavior.css";

@import "@gunkin/uiify/styles/tokens";

@import "@gunkin/uiify/styles/tailwind";

@import "tailwindcss/utilities.css";

@theme { --spacing: 0.25rem; --font-weight-normal: 400; --font-weight-medium: 500; --font-weight-semibold: 600; --font-weight-bold: 700; }

@source inline('grid gap-md w-max max-w-[min(28rem,calc(100vw_-_2_*_var(--space-lg)))] p-6 border border-border rounded-xl [corner-shape:squircle] bg-card text-card-foreground shadow-popover [&[popover]:not(:popover-open)]:hidden motion-safe:[&[popover]]:[transition:var(--transition-presence)] motion-safe:[&[popover]:not(:popover-open)]:opacity-0 motion-safe:[&[popover]:not(:popover-open)]:[scale:var(--presence-scale)] motion-safe:starting:[&[popover]:popover-open]:opacity-0 motion-safe:starting:[&[popover]:popover-open]:[scale:var(--presence-scale)]');

@layer base { :root { --uiify-control-text: var(--text-sm); } @media (pointer: coarse) { :root { --uiify-control-text: var(--text-base); } } }

/* Authored animation and registered properties used by the Tailwind skin.
 * Visual rules belong in utility recipes; only at-rule definitions live here. */
@layer components {
  @keyframes uiify-presence-in {
    from {
      opacity: 0;
      scale: var(--presence-scale);
    }
  }
}

@layer components {
  @keyframes uiify-presence-out {
    to {
      opacity: 0;
      scale: var(--presence-scale);
    }
  }
}

@property --uiify-spinner-tail {
  syntax: "<angle>";
  inherits: false;
  initial-value: 0deg;
}

@property --uiify-spinner-length {
  syntax: "<angle>";
  inherits: false;
  initial-value: 36deg;
}

@layer components {
  @keyframes uiify-spinner-rotate {
    to {
      transform: rotate(360deg);
    }
  }
}

@layer components {
  @keyframes uiify-spinner-orbit {
    0% {
      --uiify-spinner-tail: 0deg;
      --uiify-spinner-length: 36deg;
    }

    50% {
      --uiify-spinner-tail: 90deg;
      --uiify-spinner-length: 324deg;
    }

    100% {
      --uiify-spinner-tail: 360deg;
      --uiify-spinner-length: 36deg;
    }
  }
}

@layer components {
  @keyframes uiify-skeleton-pulse {
    50% {
      opacity: 0.45;
    }
  }
}

@layer components {
  @keyframes uiify-skeleton-shimmer {
    to {
      background-position: -200% 0;
    }
  }
}

@layer components {
  @keyframes uiify-skeleton-reveal {
    from {
      opacity: 0;
    }
    to {
      opacity: 1;
    }
  }
}

@property --candle-body-height {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 0%;
}

@property --candle-body-top {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 50%;
}

@property --candle-slot {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 100%;
}

@property --candle-wick-height {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 0%;
}

@property --candle-wick-top {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 50%;
}

@property --candle-x {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 0%;
}

@property --candle-scale {
  syntax: "<number>";
  inherits: true;
  initial-value: 1;
}

@property --line-y {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 50%;
}

@property --line-prev-y {
  syntax: "<percentage>";
  inherits: true;
  initial-value: 50%;
}

@property --line-count {
  syntax: "<integer>";
  inherits: false;
  initial-value: 1;
}

@property --line-scale {
  syntax: "<number>";
  inherits: true;
  initial-value: 1;
}

@layer components {
  @keyframes uiify-otp-input-caret-blink {
    50% {
      opacity: 0;
    }
  }
}

API

`VirtualScroll`

Prop	Tipo	Predeterminado	Descripción
`items`*	`T[]`	—	Lista completa de elementos, cada uno con un id estable; solo se renderizan las filas del rango actual.
`renderRow`*	`(item: T, index: number) => ReactNode`	—	Renderiza el contenido de una fila a partir de su elemento y su índice absoluto.
`height`	`number`	—	Altura explícita en píxeles. Omítela y pasa style={{ blockSize: '100%' }} para ocupar una altura definida del elemento padre; si no se proporciona ninguna, el valor predeterminado es 600px.
`rowHeight`	`number`	`64`	Tamaño fijo en píxeles de cada fila sobre el eje de desplazamiento (altura en vertical, ancho en horizontal); se usa para calcular el tamaño desplazable y las filas visibles.
`orientation`	`"vertical" \| "horizontal"`	`"vertical"`	Eje de desplazamiento. Las listas horizontales se desplazan sobre el eje en línea, calculan la ventana a partir del ancho medido del área visible, se reflejan correctamente en diseños de derecha a izquierda y reflejan el valor en `data-orientation`.
`overscan`	`number`	`5`	Número de filas adicionales renderizadas antes y después del rango visible para que el desplazamiento rápido no muestre espacios vacíos.
`estimateRowHeight`	`(index: number) => number`	—	Estimación de altura por índice que cambia la lista a una distribución dinámica, donde se miden las filas renderizadas y se corrige la estimación.
`role`	`"list" \| "grid"`	`"list"`	Rol ARIA aplicado al contenedor de desplazamiento.
`anchor`	`"start" \| "end"`	`"start"`	Extremo de la lista al que permanece fijada la posición de desplazamiento al añadir o quitar elementos.
`followAppend`	`boolean \| "smooth"`	`false`	Se desplaza hasta los elementos recién añadidos cuando la lista ya está al final, opcionalmente con desplazamiento suave.
`scrollRef`	`Ref<VirtualScrollHandle>`	—	Recibe el manejador imperativo que expone scrollToIndex, scrollToOffset y scrollToEnd.
`onRangeChange`	`(range: VirtualScrollRangeChange) => void`	—	Se llama con los rangos de índices visibles y adicionales cada vez que se mueve la ventana renderizada.
`onScrollStateChange`	`(state: VirtualScrollScrollState) => void`	—	Se llama cuando comienza el desplazamiento y cuando se detiene.
`isScrollingResetDelay`	`number`	`150`	Milisegundos sin movimiento para considerar terminado el desplazamiento en navegadores sin el evento scrollend.
`className`	`string`	—	Clase aplicada al contenedor de desplazamiento.
`testId`	`string`	—	Valor del atributo data-testid del contenedor de desplazamiento.

Teclado

Tecla	Acción
`Scroll`	La rueda, el panel táctil o la barra de desplazamiento mueven la ventana
`Tab`	Mover el foco entre controles de fila (casilla de verificación, activador de menú)
`Arrow keys`	Recorrer los elementos de un menú desplegable abierto
`Escape`	Cerrar un menú desplegable abierto

Accesibilidad

Un espaciador de altura completa mantiene precisa la barra de desplazamiento nativa mientras solo se monta un conjunto fijo de espacios de fila y algunas filas adicionales; las claves estables de los espacios reciclan nodos del DOM. Las filas exponen role="listitem" con aria-posinset y aria-setsize dentro de un área de desplazamiento role="list". La sincronización del desplazamiento es pasiva y los saltos grandes, como los de la barra de desplazamiento, Home/End o Cmd+Arrow, actualizan el rango de forma síncrona.

Puntos de estilo

data-uiify-virtual-scrolldata-part="spacer"data-part="row"

Framework

Estilo

Tema

Idioma

Virtual scroll

Zona de pruebas

Virtual scroll

Horizontal

API

`VirtualScroll`

Teclado

Accesibilidad

Puntos de estilo