D3.js dentro de React: enlace de datos, SVG y la regla de propiedad de useEffect
Aprende qué es realmente D3, cómo funciona el enlace para ingresar/actualizar/salir, por qué SVG es adecuado para él, y cómo dividir el control del DOM para que D3 y React colaboren en un gráfico de barras.
Fuentes: Harnessing the Power of Data Visualization: Integrating D3.js with React
Tres cosas que debes saber primero
- D3 es una herramienta, no una biblioteca de gráficos. Aquellos que esperan algo similar a Chart.js se encuentran con dificultades. D3 es un mecanismo de bajo nivel para vincular datos con elementos DOM, lo que explica tanto su potencia como su curva de aprendizaje más pronunciada.
- React y D3 compiten por los mismos nodos DOM. La solución es sencilla: React renderiza el contenedor SVG, mientras que D3 gestiona todo lo que hay dentro mediante un
useEffect. Si ignoras esta regla, pasarás horas resolviendo conflictos extraños. - El patrón de enter, update y exit parece extraño al principio. Después de usarlo unas cuantas veces, cobra sentido, y entonces otros enfoques para gráficos basados en datos parecen torpes.
Qué es realmente D3
El nombre hace referencia a Documentos Impulsados por Datos. La palabra clave es “documentos”: elementos DOM cuyo aspecto está determinado por datos. D3 vincula arrays a elementos y permite definir su apariencia en función de los valores de esos arrays. Un gráfico es solo uno de los resultados posibles, y la propia biblioteca no tiene concepto de tipos de gráficos.
De ahí provienen tanto la fortaleza como la dificultad. D3 no toma decisiones por usted. Cada propiedad visual, cada marca en el eje, cada color y cada interacción son algo que usted especifica. Esto le brinda total libertad creativa, pero también requiere mucho trabajo de escritura.
Vinculación de datos y el DOM
Es aquí donde la mayoría de los principiantes se rinden, por lo que vale la pena explicarlo paso a paso.
En JavaScript normal, se crea un elemento, se le rellena de contenido y se inserta en la página. Con D3, se selecciona un grupo de elementos, incluidos aquellos que aún no existen, se asocia un array a esa selección y luego se reciben tres grupos como resultado:
- elementos que ya existen y solo necesitan datos actualizados (la selección de actualización),
- puntos de datos que aún no tienen elemento asociado (la selección de inserción),
- elementos cuyos datos han desaparecido (la selección de eliminación).
Lo extraño es llamar a métodos sobre una selección que está vacía. Se seleccionan todos los elementos rect dentro de un SVG que no contiene ninguno, se llama a .data(myArray), luego a .enter() y después a .append('rect'), y aparecen los rectángulos. Lo que ocurre es que .enter() genera un marcador de posición para cada dato que carece de elemento, y .append() convierte cada marcador en un nodo real. Se puede interpretar como “para cada punto de datos sin elemento, crear uno.”
Antes de que esto funcione, el código de D3 parece magia. Después, resulta comprensible de forma natural.
Establecer propiedades visuales a partir de los datos
Una vez que los datos están vinculados, el siguiente paso es más fácil de entender. Cualquier atributo o estilo puede calcularse a partir del dato:
selection.attr('height', d => yScale(d.value))
Aquí d es el dato asociado a ese elemento en particular, y yScale es una función que convierte el rango de valores en píxeles. La altura de la barra es una función directa de sus datos. Al modificar los datos y ejecutar la línea de código nuevamente, la altura cambia en consecuencia. Casi todo en una visualización D3 se reduce a variaciones de esta idea: establecer una propiedad visual como una función del valor límite.
¿Por qué SVG?
D3 dibuja en SVG, y las razones van más allá de la historia.
SVG es basado en vectores, por lo que las formas se definen matemáticamente en lugar de como rejillas de píxeles. Un gráfico de barras nítido en una laptop lo es igualmente en una pantalla 4K sin necesidad de esfuerzos adicionales, y las exportaciones no se vuelven borrosas en resoluciones inadecuadas.
Lo que es más importante para la interactividad es que las formas SVG son elementos DOM normales y forman parte del sistema de eventos del navegador al igual que un botón. Las acciones de pasar el cursor, hacer clic y tocar funcionan sin necesidad de pruebas de colisión personalizadas, ya que basta con adjuntar oyentes.
El costo se hace evidente a gran escala: miles de nodos SVG ralentizan la página, por lo que representar 50,000 puntos separados como elementos individuales afectará negativamente el rendimiento. El renderizado en Canvas se adapta mejor a esa situación. Para paneles de control, gráficos empresariales y la mayoría de las herramientas analíticas, SVG es adecuado y la integración de eventos vale la pena.
Interactividad y flexibilidad
En las interfaces de exploración de datos, donde los usuarios dividen, filtran e inspeccionan la información desde distintos ángulos, D3 supera a las herramientas de creación de gráficos estáticos. Usted controla cada evento y transición.
La mayoría de las bibliotecas de gráficos ofrecen tipos de gráficos listos para configurar: barras, líneas, circulares, con opciones de colores, etiquetas y leyendas. D3, en cambio, proporciona componentes básicos: escalas, ejes, generadores de trazados y algoritmos de disposición. Un tipo de gráfico es simplemente una combinación de estos componentes, por lo que no existe una lista de los que están soportados. Si no existe una visualización ya preparada, puedes crearla tú mismo, limitado únicamente por SVG y las matemáticas.
El costo implica trabajo adicional. Si vale la pena depende del proyecto. Para gráficos empresariales estándar, Recharts o Chart.js son suficientes y puedes seguir adelante. Para gráficos interactivos personalizados donde la presentación es crucial, D3 es la opción más adecuada.
Las funciones que usarás constantemente
Esto no es una referencia completa, solo las funciones que se utilizan en el trabajo diario:
- d3.select() obtiene el primer elemento que coincide con un selector. En React,
d3.select(svgRef.current)es la forma habitual de acceder al contenedor. - d3.selectAll() devuelve todos los elementos que coinciden. Por lo general, el enlace de datos comienza aquí porque hay varios elementos involucrados.
- selection.data() asocia cada elemento del array a un elemento concreto, de modo que
desté disponible en llamadas posteriores. Todo lo demás depende de este paso. - selection.enter() proporciona una selección temporal para los datos que no tienen nodo, y
.append()crea los nodos posteriormente. - selection.attr() establece atributos, como la línea de altura mostrada anteriormente, algo que escribirás cientos de veces.
.attr() o .style() y los valores se interpolan de forma suave, convirtiendo un salto brusco en una animación.d3.max(data, d => d.value).Usar D3 dentro de React
El problema del que nadie habla hasta que uno se topa con él: React mantiene un DOM virtual y aplica sus propios cambios al DOM real, mientras que D3 edita directamente el DOM real. Si ambos operan dentro de un mismo elemento, la vuelta a renderizar de React sobrescribe el trabajo de D3, o D3 inserta nodos de los que React no tiene conocimiento, lo que confunde la siguiente renderización.
El enfoque que funciona es dividir las responsabilidades. React renderiza el contenedor SVG y no modifica nada dentro de él. D3 accede a ese contenedor a través de un ref y realiza todo su trabajo dentro de un useEffect. Cuando los datos cambian, una actualización de estado activa ese efecto, y D3 limpia y vuelve a dibujar. Ninguna de las bibliotecas interfiere con la otra.
1. Instalar los paquetes
Agrega D3 junto con React y ReactDOM mediante tu gestor de paquetes.
npm install d3 react react-dom
Los usuarios de Yarn hacen lo mismo con su propio comando add.
yarn add d3 react react-dom
2. Escribir el componente
El lado de React tiene una sola tarea: renderizar un elemento SVG y entregarle a D3 un ref hacia él. Nada más dentro de la visualización pertenece a React.
3. Dibujar en useEffect
Dentro del efecto, escriba código D3 tal como lo haría fuera de React, utilizando el ref para encontrar el contenedor. Dos escalas se encargan del cálculo de coordenadas: una mapea las etiquetas de categoría a posiciones horizontales y la otra mapea los valores de datos a posiciones verticales. La altura de cada barra es el borde inferior del gráfico menos el valor escalado. Esta parte confunde a muchas personas porque el eje y de SVG apunta hacia abajo, por lo que las barras más altas corresponden a valores y más pequeños.
4. Renderizar el componente
Coloque el componente en su aplicación y pásele un array de datos. Al cambiar el array, el gráfico se vuelve a dibujar: React detecta el cambio en la propiedad, se activa el efecto correspondiente y D3 limpia y vuelve a dibujar el gráfico. La conexión entre el estado de la aplicación y la visualización es automática.
5. Inicie la aplicación
Ejecute el servidor de desarrollo con npm.
npm start
O con Yarn.
yarn start
Verá un gráfico de barras en el navegador. A partir de ahí, todo sigue el mismo patrón: indicadores al pasar el cursor, escalas de colores, actualizaciones animadas, zoom y otros tipos de gráficos. Todo esto forma parte de ese efecto y utiliza las funciones mencionadas anteriormente.
Resumen
D3 y React colaboran una vez que la estructura está definida. React se encarga del contenedor y del ciclo de vida de los componentes, mientras que D3 se ocupa de la representación gráfica en su interior. Mantenga esta separación clara para que cada biblioteca haga lo para lo que fue diseñada.
La ventaja es la posibilidad de crear visualizaciones que ningún paquete de gráficos incluye, ya que trabaja con elementos primitivos y no con opciones de configuración. Cuando el propio gráfico forma parte del valor del producto, eso es importante. Cuando un panel de control solo necesita un gráfico de líneas, utilice Recharts y evite los pasos adicionales.
Leer más
- El Arnés Es el Producto: Una Guía Práctica sobre los Arneses en la IA Agente — Aprenda qué es un arnés para agentes y sus siete componentes, desde herramientas y contexto hasta límites y evaluaciones, además de subagentes, modos de fallo y marcos que vale la pena conocer.
- Ingeniería de Arneses: El Entorno que Hace Fiables a los Agentes de IA — Qué es la ingeniería de arneses, sus seis componentes y tres pilares, cómo surgió el término en 2026, y nueve principios de diseño para agentes en producción.