Barra de progreso circular en SVG: fórmula y stroke-dashoffset

Contenido
- Por qué hay que calcular al crear una barra de progreso circular
- Cómo calcular la circunferencia en SVG y crear el código CSS tú mismo
- Valores de stroke-dashoffset según el progreso y consejos de diseño
- Tabla de referencia de radios y circunferencias por tamaño habitual
- Conclusión
- Mecanismo técnico clave: cómo funciona una barra de progreso circular en SVG
- Tabla comparativa por caso: matriz de técnicas para implementar un progreso circular
- 5 errores habituales al crear una barra de progreso circular
- Flujo de trabajo en 5 pasos para crear una barra de progreso circular en SVG sin fallos
- 7 consejos para tu barra de progreso circular en SVG
- Árbol de decisión para elegir la tecnología de renderizado (Decision Tree)
- Chuleta de terminología (Terminology Cheatsheet)
- Preguntas frecuentes
Para mostrar un porcentaje de progreso con un indicador circular en las tarjetas de estadísticas de un panel o en una pantalla de espera de carga de archivos, no basta con cambiar el width como en una barra rectangular. Hay que calcular la longitud de la circunferencia del círculo SVG y pasarla como valor de stroke-dasharray y stroke-dashoffset para que parezca llenarse hasta donde quieres. Cada vez que cambian el tamaño (el diámetro), el grosor de la línea o el porcentaje objetivo, hay que volver a obtener el radio y repetir este cálculo a mano; por eso, si entiendes el principio, puedes verificar por tu cuenta por qué sale ese valor.
Resumen ① En la barra de progreso circular, la longitud de la circunferencia se declara con
stroke-dasharrayy el tramo restante se oculta constroke-dashoffsetpara representar el avance. ② Tomando como base un tamaño (diámetro) de 120px, un grosor de línea de 8px y un progreso del 75%, el radio es de 56px, la circunferencia ≈ 351.86px y elstroke-dashoffset≈ 87.96px. ③ También puedes ajustar solo el tamaño del círculo, el grosor, el color y el progreso, sin calcular nada a mano, y obtener directamente el código SVG y CSS.
Por qué hay que calcular al crear una barra de progreso circular
En una barra de progreso rectangular normal basta con cambiar el ancho (width) de la parte rellena en porcentaje, pero con una barra circular no funciona así. El elemento SVG <circle> puede dibujar su borde (stroke) como línea continua o como línea discontinua con stroke-dasharray; si ajustas ese intervalo de discontinuidad a la longitud total de la circunferencia, puedes expresar el progreso como "hasta dónde está dibujada la línea y desde dónde queda vacía". Por eso, para crear un indicador circular primero necesitas conocer la longitud de la circunferencia y luego calcular cuánto hay que ocultar según el porcentaje de avance.
Cómo calcular la circunferencia en SVG y crear el código CSS tú mismo
El orden de los cálculos tiene dos etapas.
- Radio (r) = (tamaño (diámetro) − grosor de línea) ÷ 2
- Circunferencia (C) = 2 × pi (π) × radio (r)
- stroke-dashoffset = circunferencia (C) × (1 − progreso (P) ÷ 100)
Con un tamaño (diámetro) de 120px, un grosor de línea de 8px y un progreso objetivo del 75%, quedaría así.
- Radio: (120 − 8) ÷ 2 = 56px (como la línea se dibuja sobre la línea central del círculo, se desplaza hacia dentro la mitad del grosor de la línea)
- Circunferencia: 2 × 3.14159 × 56 ≈ 351.86px
- stroke-dasharray: 351.86 (se declara tal cual la longitud total de la circunferencia)
- stroke-dashoffset: 351.86 × (1 − 0.75) ≈ 87.96px (se oculta el 25% restante)
El marcado y el CSS para crear una barra de progreso circular con un 75% de avance son los siguientes.
<div class="progress-circle-container">
<svg class="progress-ring" width="120" height="120">
<!-- pista del círculo de fondo -->
<circle class="progress-ring-bg" stroke="#e2e8f0" stroke-width="8" fill="transparent" r="56" cx="60" cy="60" />
<!-- pista del círculo de progreso -->
<circle class="progress-ring-bar" stroke="#3b82f6" stroke-width="8" stroke-linecap="round" fill="transparent" r="56" cx="60" cy="60" />
</svg>
<span class="progress-text">75%</span>
</div>
.progress-ring { transform: rotate(-90deg); /* gira el punto de inicio para que se llene desde las 12 en punto */ }
.progress-ring-bar { stroke-dasharray: 351.86; stroke-dashoffset: 87.96; /* estado de progreso al 75% / transition: stroke-dashoffset 0.8s ease-in-out; / transición suave cuando cambia el valor del porcentaje */ }
Nota No hace falta teclear cada vez pi y el radio en la calculadora para obtener los píxeles de
stroke-dashoffset: puedes ajustar con deslizadores el tamaño del círculo, el grosor, el color y el progreso (%), y copiar el código SVG y CSS tal cual.
Si en lugar de calcular los valores y editar el código a mano prefieres cambiar solo el progreso y los estilos y ver el resultado al instante, compruébalo con nuestra herramienta.
Ajusta el porcentaje de progreso (%), el tamaño del círculo (diámetro), el grosor del indicador y el color, y obtén al instante el código SVG y CSS de tu gráfico circular optimizado.

Valores de stroke-dashoffset según el progreso y consejos de diseño
Tomando como base un tamaño (diámetro) de 120px y un grosor de línea de 8px (radio 56px, circunferencia ≈ 351.86px), los valores de stroke-dashoffset según el progreso son los siguientes.
| Progreso | stroke-dashoffset |
|---|---|
| 25% | 263.89px |
| 50% | 175.93px |
| 75% | 87.96px |
| 100% | 0px |
Hay dos cosas que conviene tener en cuenta al aplicar el diseño.
- Girar el punto de inicio a las 12 en punto: la posición inicial predeterminada del
<circle>de SVG es a las 3 en punto. Para que se llene en sentido horario desde las 12, aplicatransform: rotate(-90deg)al elemento SVG. - Redondear los extremos: para redondear ambos extremos del indicador de progreso, añade
stroke-linecap: round. Da una impresión más suave, como de infografía.
Tabla de referencia de radios y circunferencias por tamaño habitual
Desde círculos pequeños como un badge hasta tarjetas de panel grandes, cuando cambia la combinación de tamaño (diámetro) y grosor de línea, el radio y la circunferencia también cambian. Si aplicas la fórmula radio = (diámetro − grosor de línea) ÷ 2 y sacas los valores de antemano, puedes consultarlos directamente en la tabla de abajo sin recalcularlos para cada tamaño de pantalla.
| Tamaño (diámetro) | Grosor de línea | Radio | Circunferencia |
|---|---|---|---|
| 80px | 6px | 37px | ≈232.48px |
| 120px | 8px | 56px | ≈351.86px |
| 160px | 10px | 75px | ≈471.24px |
| 200px | 12px | 94px | ≈590.62px |
Ten en cuenta que, con el mismo progreso, cuanto mayor es el tamaño, más aumenta la circunferencia y con ella el valor de stroke-dashoffset. Por ejemplo, en la combinación de tamaño 200px y grosor de línea 12px con un progreso del 75%, el stroke-dashoffset es 590.62 × 0.25 ≈ 147.65px.
Conclusión
- En la barra de progreso circular, la circunferencia (C = 2 × π × r) se expresa con
stroke-dasharrayy el tramo restante constroke-dashoffset. - El radio (r) es la mitad del tamaño (diámetro) menos el grosor de línea, y con la fórmula stroke-dashoffset = circunferencia × (1 − progreso ÷ 100) puedes calcular el valor del porcentaje que quieras.
- La rotación del punto de inicio (
rotate(-90deg)) y el tratamiento de los extremos (stroke-linecap: round) influyen en el acabado del diseño. - Si el tamaño, el grosor de línea o el progreso cambian con frecuencia, es más rápido obtener directamente el código SVG y CSS con la herramienta que calcular los valores a mano.
Ajusta el porcentaje de progreso (%), el tamaño del círculo (diámetro), el grosor del indicador y el color, y obtén al instante el código SVG y CSS de tu gráfico circular optimizado.
Mecanismo técnico clave: cómo funciona una barra de progreso circular en SVG
Vamos a desglosar en detalle el mecanismo interno de una barra de progreso circular en SVG: cómo se calcula matemáticamente y cómo se renderiza de forma visualmente fluida. Ve más allá de copiar y pegar código: para abordar aplicaciones complejas necesitas entender el principio exacto con el que el navegador dibuja un círculo en pantalla.
1. Geometría de coordenadas y cálculo del radio en el trazo de un círculo SVG
El lienzo de SVG lo forman el viewport y el viewBox. Imagina, por ejemplo, un sistema de coordenadas que ocupa un espacio de D x D (120 x 120px). En SVG, el trazo (stroke) siempre se extiende a partir de la línea central de la ruta (path) dibujada. Es decir, si el grosor del trazo (strokeWidth) es de 8px, 4px ocupan la parte interior de la ruta y los otros 4px, la exterior. Por lo tanto, para que el círculo se dibuje completo y no quede recortado por el borde de la pantalla, si quieres que su diámetro sea de 120px, el radio de la ruta que debes programar debe ser la mitad, 60px, menos la mitad del grosor del trazo (4px).
- Fórmula del radio real (True Radius Formula): r = D − StrokeWidth/2 = 120 − 8/2 = 56px
Con el radio obtenido, calculas la longitud total del contorno del círculo. La circunferencia, es decir, el perímetro del círculo, se obtiene con la fórmula más básica de la geometría.
- Fórmula de la circunferencia real (True Circumference Formula): C = 2π r = 2 × 3.1415926535... × 56 ≈ 351.858377px
Este valor (aproximadamente 351.86) se convierte en el punto de referencia más importante para controlar el progreso de aquí en adelante.
2. La física del enmascarado al renderizar con CSS dash offset
Con la función de segmentos discontinuos (dash) del trazo SVG puedes crear una barra de progreso en lugar de una línea continua. La clave está en hacer que la longitud del segmento sea exactamente igual a la longitud total de la circunferencia.
- stroke-dasharray: C C; Esta propiedad define la longitud de la parte dibujada y la del espacio en blanco. Si pones C (351.86), un único segmento largo rodeará el círculo completo a la perfección.
- stroke-dashoffset: C × (1 − Progress/100)
Esta propiedad desplaza (offset) el punto donde empieza el segmento. Produce un efecto físico de enmascarado, como si colocaras una cortina.
- Con un progreso del 0%: Offset = C (351.86px). El segmento se desplaza hacia atrás toda la circunferencia y solo se ve una pista vacía al 0%.
- Con un progreso del 50%: Offset = 0.5C (175.93px). Como solo se desplaza la mitad, se visualiza un indicador con medio círculo lleno.
- Con un progreso del 100%: Offset = 0px. No se desplaza nada y el segmento llena todo de principio a fin, así que se completa un círculo perfectamente cerrado.
3. Rotación del sistema de coordenadas
En el sistema de coordenadas trigonométrico básico de SVG, el punto de inicio de 0 radianes, es decir, el ángulo 0, está en la dirección de las 3 en punto (a la derecha, x=r, y=0). Sin embargo, las barras de progreso y los relojes que vemos a diario suelen empezar a las 12 en punto (arriba del todo) y avanzar en sentido horario. Para lograr esta interfaz intuitiva, debes rotar el elemento SVG renderizado 90 grados en sentido antihorario.
- transform: rotate(-90deg); Y, en este caso, debes establecer obligatoriamente un punto de referencia para que el eje de rotación quede justo en el centro del círculo, como transform-origin: 50% 50%; o rotate(-90deg 60 60). Si omites esta configuración, el círculo trazará una órbita absurda y saldrá despedido fuera del viewport: un auténtico desastre.
Tabla comparativa por caso: matriz de técnicas para implementar un progreso circular
Hay muchas formas de dibujar un indicador de progreso circular en la web. Compara las características, ventajas y desventajas de cada técnica para elegir la mejor opción según la situación de tu proyecto.
| Criterio de comparación | SVG puro + stroke-dashoffset (recomendado) | CSS conic-gradient() + máscara | arc() de Canvas HTML5 | GIF animado / Lottie | Shader de WebGL |
|---|---|---|---|---|---|
| Nitidez al escalar vectores | Escalado infinito (perfectamente nítido) | Depende del renderizado del navegador | Requiere un tratamiento aparte para alta resolución (Retina) | Pierde nitidez al ampliar o el tamaño del archivo se dispara | Muy nítido (aunque es una solución sobredimensionada) |
| Compatibilidad con animaciones CSS (transition) | Compatibilidad total (fluida y sencilla) | Parcial (requiere especificaciones modernas como @property) | No compatible (hay que programarla manualmente con JS mediante requestAnimationFrame) | Depende del reproductor de Lottie | No compatible (requiere un bucle de renderizado en JS) |
| Peso del bundle inicial y tamaño del archivo | El más ligero (menos de 1KB aprox.) | El más ligero | Medio (requiere lógica para controlar el canvas) | Muy pesado (de cientos de KB a MB) | Pesado (librerías como Three.js) |
| Dificultad de implementación y mantenimiento | Fácil (solo hay que conocer la fórmula matemática) | Muy fácil | Algo complejo | Dependencia muy alta del diseñador | Muy difícil |
| Compatibilidad entre navegadores | Compatibilidad total con todos los navegadores | Tiene limitaciones en navegadores antiguos | Excelente | Depende de la librería | Provoca calentamiento en dispositivos de gama baja |
Resumen de la comparación: El método más extendido y con mayores ventajas de rendimiento es, sin duda, el basado en SVG puro. Pesa como una pluma, se lleva de maravilla con las animaciones CSS y presume de una nitidez que no pierde ni un solo píxel en ninguna pantalla.
5 errores habituales al crear una barra de progreso circular
Al crear un gráfico de progreso circular, muchos desarrolladores de frontend cometen sin darse cuenta errores graves. Con solo revisar estos cinco puntos puedes reducir drásticamente el tiempo de depuración.
- Calcular el radio sin tener en cuenta el grosor del trazo (error de recorte): El error consiste en dividir el diámetro total entre 2 y no restar la mitad del grosor del trazo (stroke-width). Esto hace que el borde se salga del viewBox y que los lados superior, inferior, izquierdo y derecho del círculo se vean achatados y cortados. No olvides nunca la fórmula r = (D − S)/2.
- Omitir el punto de referencia (transform-origin) al rotar: Ocurre cuando aplicas rotate(-90deg) para girar el elemento SVG hacia las 12 en punto y te olvidas de transform-origin: center; (o 50% 50%). El círculo pierde su eje central y desaparece hacia la esquina superior izquierda de la pantalla.
- Dejar los extremos sin redondear (omitir stroke-linecap): Si olvidas stroke-linecap: round;, que redondea los extremos de la línea, los dos extremos de la barra de progreso quedan romos y angulosos, como cortados a cuchillo. Es el principal enemigo del acabado del diseño, sobre todo cuando el progreso es bajo.
- Errores por usar un valor impreciso de π: Si calculas el valor de π simplemente como 3.14, el valor en píxeles de la circunferencia se desvía ligeramente. Como resultado, incluso con un progreso del 100% queda un hueco minúsculo (gap) y la línea no se cierra del todo: aparece un error. Debes usar Math.PI de JavaScript o, como mínimo, 4 decimales (3.1416) o más.
- Animaciones entrecortadas por no aplicar will-change: En paneles complejos o sistemas de monitoreo en tiempo real en los que los datos cambian sin parar, si no optimizas la animación CSS con will-change: stroke-dashoffset;, el motor de renderizado del navegador se sobrecarga y la animación puede entrecortarse.
Flujo de trabajo en 5 pasos para crear una barra de progreso circular en SVG sin fallos
Esta es la guía paso a paso para diseñar el componente de la forma más estable y precisa posible.
- Paso 1: define el tamaño del lienzo SVG y el grosor del trazo Decide el tamaño total que ocupará el componente en pantalla (D) y el grosor del trazo que vas a dibujar (S). Por ejemplo: D = 120px, S = 8px.
- Paso 2: obtén el radio real (r) con matemáticas Para que no se recorte dentro del viewBox, calcula r = (D − S)/2. Por ejemplo: (120 − 8)/2 = 56.
- Paso 3: calcula la circunferencia (C, la longitud total del perímetro) y asigna variables Obtén la circunferencia con la fórmula C = 2 × π × r. Por ejemplo: 2 × 3.14159 × 56 = 351.86. Guarda ese valor en una variable de CSS o de JS (CSS Custom Property).
- Paso 4: coloca la pista de fondo y el círculo de primer plano (progreso) Usa 2 etiquetas <circle>: una como línea de fondo tenue en tonos grises y otra como línea de progreso con el color de la marca. Aplica a ambas los atributos r, cx y cy que obtuviste antes.
- Paso 5: aplica transiciones CSS y la fórmula dinámica de dash offset Asigna stroke-dasharray: 351.86; al <circle> de primer plano y actualiza dinámicamente la propiedad stroke-dashoffset según el porcentaje (P) que recibas desde tu framework de JavaScript (React, Vue, etc.). Añade transition: stroke-dashoffset 0.6s ease-out; para rematar la animación.
7 consejos para tu barra de progreso circular en SVG
Siete consejos avanzados para llevar la experiencia de usuario (UX) mucho más allá de una implementación básica.
- Extremos suaves con un toque moderno: para que el diseño no se vea anguloso ni tosco, no olvides el atributo stroke-linecap="round". Así conservas el aire moderno del diseño circular.
- Aplica degradados de varios colores (multi-stop gradient): en lugar de un trazo de un solo color, define un <linearGradient> o un <radialGradient> dentro de <defs> y aplícalo con stroke="url(#myGradient)". Conseguirás un indicador lleno de vida.
- Usa el anclaje de texto centrado: cuando muestres el porcentaje de progreso con una etiqueta <text>, añade los atributos dominant-baseline="central" y text-anchor="middle" y te bastará con x="50%" y="50%" para lograr una alineación perfecta en horizontal y vertical.
- Rotación in situ sin errores: para que el elemento no se desplace durante una animación de rotación, define transform-origin: 50% 50%; o usa directamente el atributo interno de SVG transform="rotate(-90 cx cy)" en lugar de CSS.
- Adáptalo a un indicador semicircular tipo velocímetro: si en vez de un círculo de 360 grados quieres un indicador de 180 grados como el velocímetro de un coche, limita stroke-dasharray a la mitad de la circunferencia total (0.5C) y ajusta el ángulo de rotación del punto de inicio. Así se implementa sin complicaciones.
- Actualizaciones fluidas de flujos de datos: cuando los datos cambian varias veces por segundo, como en cotizaciones bursátiles o en el monitoreo de sensores, usa linear en lugar de una función de easing habitual como ease-out, o apóyate en la interpolación de D3.js. La pantalla se verá mucho más fluida.
- Apóyate en un generador de código repetitivo: no hace falta volver a escribir todas estas fórmulas cada vez que cambies el tamaño o el grosor. La sabiduría de quien trabaja en esto consiste en usar el Generador de barra de progreso circular en CSS que tienes al inicio de esta página y sacar el código ya terminado al instante.
Árbol de decisión para elegir la tecnología de renderizado (Decision Tree)
Descubre de un vistazo cuándo conviene usar SVG y cuándo otra tecnología.
- P: ¿La línea del borde debe verse perfectamente nítida al ampliar o reducir la pantalla?
- No ➔ Considera Canvas o WebGL.
- Sí ➔ Pasa al punto 2.
- P: ¿Necesitas una animación en la que el progreso avance suavemente según el porcentaje (%)?
- No ➔ Un conic-gradient() en CSS puro es lo más sencillo.
- Sí ➔ Pasa al punto 3.
- P: ¿Quieres combinarlo con frameworks como React o Vue y minimizar el tamaño del bundle?
- No ➔ Usa animaciones Lottie o una librería de terceros.
- Sí ➔ Respuesta correcta: la técnica SVG + stroke-dashoffset (la combinación más perfecta)
Con este árbol de decisión llegarás a la conclusión de que, en la mayoría de los entornos de UI web actuales, el enfoque matemático basado en SVG es la respuesta correcta.
Chuleta de terminología (Terminology Cheatsheet)
Un repaso breve de los términos imprescindibles para la visualización web. Úsalos para no liarte en las revisiones de código ni en las conversaciones con tu equipo.
- Circunferencia (Circumference): es la longitud total del borde de un círculo. Su fórmula es 2 × π × r. A partir de esa longitud se decide la longitud del trazo.
- stroke-dasharray: propiedad que convierte un trazo SVG en una línea de puntos. Si le das el mismo valor que la circunferencia, obtienes un único y enorme trozo de línea de puntos.
- stroke-dashoffset: determina cuánto se desplaza el punto donde empieza la línea de puntos. Con un progreso del 0% se desplaza por completo la longitud de la circunferencia, y con el 100% se deja en 0.
- stroke-linecap: round: propiedad que hace que el inicio y el final del trazo se rendericen con una curva redondeada en lugar de con un ángulo recto.
- viewBox: propiedad que define la proporción lógica del lienzo y el sistema de coordenadas en el que se dibuja el gráfico dentro del SVG; lo que queda fuera de él aparece recortado (clip) y no se ve.
- Escalado vectorial (Vector Scaling): como la imagen se dibuja con fórmulas matemáticas y no como un conjunto de píxeles, no se rompe por mucho que amplíes la pantalla sin límite.
Preguntas frecuentes
Tres preguntas en profundidad que van al fondo de la técnica, con respuestas claras.
P1. ¿Por qué, al calcular el radio (r) de un SVG, hay que restar la mitad del grosor del trazo (stroke-width) a la mitad del diámetro total del lienzo?
R1. El motor de renderizado SVG del navegador dibuja el trazo (stroke) extendiéndolo con exactamente el mismo grosor hacia ambos lados de una línea central (path) invisible que le sirve de referencia. Si el trazo mide 20px, se dibujan 10px hacia dentro de la línea central y 10px hacia fuera. Si ajustas el radio justo hasta el borde del lienzo, esos 10px que deberían dibujarse hacia fuera se salen del límite del lienzo del SVG (viewBox) y se recortan de golpe sin llegar a verse en pantalla. Para evitarlo, se desplaza la propia línea central hacia dentro justo la mitad del grosor del trazo, de modo que todo el trazo quede dentro de la zona segura.
P2. ¿Cómo puedo aplicar un degradado multicolor vistoso en lugar de un color plano al trazo circular de un SVG?
R2. La propiedad background-image de CSS normal no sirve para controlar el color del trazo dentro de un SVG. En su lugar, declara un elemento <defs> al principio del marcado SVG y crea dentro una etiqueta <linearGradient> o <radialGradient>. Define ahí los puntos de los distintos colores, por ejemplo <stop offset="0%" stop-color="red" />, y asigna un id al elemento del degradado (por ejemplo id="myGrad"). Por último, en la propiedad stroke del <circle>, haz referencia al id del degradado con stroke="url(#myGrad)" y tendrás un degradado que se sucede suavemente a lo largo del trazo.
P3. ¿Qué diferencia de fondo hay entre un gráfico circular hecho con la función conic-gradient() de CSS puro y el enfoque basado en SVG?
R3. El conic-gradient() de CSS colorea el fondo (background) del elemento en forma de cono, como si fueran porciones de pizza. Tiene la gran ventaja de que el código es extremadamente corto y fácil de implementar, pero también un inconveniente serio: resulta muy complicado conseguir que, cuando cambia el porcentaje de progreso, el relleno avance de forma suave y natural con un efecto de transition (animación) de CSS. (Con la especificación moderna @property se puede, pero se pierde el soporte en navegadores antiguos). En cambio, la técnica SVG stroke-dashoffset admite de forma nativa animaciones a 60fps asombrosamente fluidas en prácticamente todos los navegadores, y es mucho más fácil implementar el detalle de redondear los extremos del trazo (round). Para interfaces dinámicas y atractivas, el enfoque SVG siempre lleva ventaja.
;
Este artículo está adaptado de nuestro original en coreano. Leer el original en coreano