Barra de progreso circular en SVG: cómo se rellena y calcula

Contenido
- Por qué una barra de progreso circular parece llenarse como un donut
- Cómo comprobarlo: dibujarlo tú mismo calculando la circunferencia
- Los puntos donde más gente se atasca
- En resumen
- El mecanismo técnico en detalle: las matemáticas de SVG y CSS
- Tabla comparativa de formas de implementar una UI circular
- 5 errores habituales al crear una barra de progreso circular en SVG
- Flujo de trabajo en 5 pasos para crear una barra de progreso circular sin fallos
- 7 consejos para animar SVG
- Árbol de decisión técnico: ¿qué enfoque te conviene?
- Glosario de términos clave (guía rápida)
- Preguntas frecuentes
Seguro que has visto barras de progreso circulares que se van llenando despacio, como un donut, en la pantalla de carga de una app o en las tarjetas de estadísticas de un panel. No son imágenes prediseñadas ni GIF animados: son el resultado de dibujar solo una parte del trazo del borde de un único círculo SVG. Si entiendes el principio, puedes reproducirlo con tu propio código sin ninguna librería.
Resumen ① Una barra de progreso circular no es una imagen, sino el trazo (stroke) del borde de un elemento SVG circle ② Con stroke-dasharray se traza una línea de la longitud total de la circunferencia, y con stroke-dashoffset se empuja el tramo que no debe verse ③ Con la circunferencia (2πr) y el porcentaje de progreso puedes calcular esos dos valores por tu cuenta
Por qué una barra de progreso circular parece llenarse como un donut
Un elemento SVG circle tiene, de forma nativa, un fill (relleno interior) y un stroke (línea del borde) independientes. Si dejas el fill transparente y pintas solo el stroke con grosor, obtienes un anillo con forma de donut; si superpones dos de estos anillos, abajo queda un círculo de fondo tenue y arriba un círculo de color que solo se ve hasta el porcentaje de progreso.
La razón por la que el círculo superior se ve "solo hasta el porcentaje de progreso" es el atributo stroke-dasharray. Originalmente sirve para dibujar líneas discontinuas, alternando un trazo (dash) y un hueco (gap); si ajustas ese valor exactamente a la longitud total de la circunferencia, un solo dash coincide con una vuelta completa del círculo y la línea se ve continua, sin cortes.
Si además añades stroke-dashoffset, puedes desplazar el punto de inicio de esa línea a lo largo de la circunferencia. Al empujar la línea una distancia igual al offset, esa parte queda escondida en el lado opuesto del círculo y da la impresión de que solo está rellena una porción; y si giras el círculo -90 grados con transform, el punto de inicio pasa de las 3 en punto a las 12 en punto.
Cómo comprobarlo: dibujarlo tú mismo calculando la circunferencia
Con unas pocas líneas de código puedes hacer el cálculo sin librerías. Primero, el radio (r) es el diámetro del círculo menos la mitad del grosor del trazo. Como el trazo se dibuja siguiendo la línea central del círculo, hay que reservar hacia dentro un espacio igual al grosor del trazo para que los dos círculos no se solapen.
Con el radio ya calculado, la circunferencia se obtiene con la fórmula "2 × π × r". Por ejemplo, si el diámetro es de 120px y el grosor del trazo de 8px, el radio es 56px, la circunferencia es de unos 351.86px y, si pones ese valor tal cual en stroke-dasharray, el círculo entero se dibuja como una sola línea continua.
Para reflejar el progreso, calcula stroke-dashoffset como "circunferencia × (1 − progreso ÷ 100)". Si el progreso es del 75%, basta con usar como offset 351.86 × 0.25, es decir, unos 87.96px. Con esos dos valores y un giro de -90 grados en la etiqueta circle, tienes lista la barra de progreso tipo donut.
Compruébalo con nuestra herramienta. Cada vez que mueves los deslizadores de progreso, grosor y tamaño, la circunferencia y el offset se recalculan automáticamente, así que puedes ver el resultado y el código al instante sin volver a calcular los valores a mano.
Gratis · sin registro · genera el código SVG y CSS directamente en el navegador

Los puntos donde más gente se atasca
| Situación | Causa |
|---|---|
| El progreso avanza en sentido contrario | Has puesto el signo del cálculo de stroke-dashoffset al revés o has indicado mal el sentido del giro |
| El punto de inicio está a la derecha (a las 3 en punto) en lugar de arriba | No has aplicado transform: rotate(-90deg) al circle |
| Los centros de grosor del círculo de fondo y del círculo de progreso no coinciden | No has restado la mitad del grosor del trazo en el cálculo del radio |
| Al cambiar el progreso se ve un salto brusco | No has aplicado transition a stroke-dashoffset, así que el valor cambia sin animación |
Como ves en la tabla, casi todos los desajustes vienen de una de dos cosas: el signo del offset o el sentido del giro. Una vez que fijas la fórmula y el giro de -90 grados, después solo tienes que ir cambiando la cifra del progreso.
En resumen
Una barra de progreso circular no es una imagen: se construye trazando con stroke-dasharray el borde de un círculo SVG a lo largo de toda la circunferencia y empujando con stroke-dashoffset el tramo que no debe verse. Con la circunferencia (2πr) y el porcentaje de progreso, puedes calcular ambos valores.
En lugar de calcular el radio y la circunferencia a mano cada vez, cambia los valores con los deslizadores y mira cómo cambia el código sobre la marcha: así cometes menos errores.
Gratis · sin registro · genera el código SVG y CSS directamente en el navegador
El mecanismo técnico en detalle: las matemáticas de SVG y CSS
Detrás de un gráfico tipo donut que parece sencillo se esconden geometría precisa y física de CSS.
Geometría del círculo SVG y matemáticas del trazo (Geometry & Stroke Math)
- Medidas totales del SVG: W × H (por ejemplo: 120 × 120px)
- Grosor del trazo (Stroke Width): S (por ejemplo: 8px)
- Radio seguro (Radius): como el trazo se reparte a ambos lados del centro, r = W/2 − S/2 = 60 − 4 = 56px
- Circunferencia (Circumference): C = 2π r ≈ 2 × 3.14159265 × 56 ≈ 351.86px
El motor físico de las propiedades dash de CSS (Physics)
- 'stroke-dasharray: C C': fija la longitud de cada fragmento (dash) de la línea discontinua igual a la circunferencia total del círculo, de modo que se vea como una línea continua.
- 'stroke-dashoffset: C \times (1 - P / 100)': cuando P es el porcentaje de progreso, desplaza el punto de inicio de la línea a lo largo de la circunferencia exactamente esa cantidad. La parte desplazada no se ve, así que se produce el efecto de tener coloreado solo el porcentaje deseado.
Rotación del sistema de coordenadas y antialiasing (Rotation & Anti-aliasing)
- El punto de referencia de 0 grados en SVG es, por convención geométrica, la dirección de las 3 en punto (x=r, y=0).
- Para que empiece a las 12 en punto (arriba), hay que indicar mediante CSS 'transform: rotate(-90deg);' y el eje de rotación 'transform-origin: center;'.
- La animación de llenado suave se implementa con 'transition: stroke-dashoffset 0.6s cubic-bezier(0.4, 0, 0.2, 1);', y para redondear el extremo de la línea se usa 'stroke-linecap: round;'.
Tabla comparativa de formas de implementar una UI circular
Hemos comparado las características de varias técnicas para implementar una barra de progreso circular.
| Criterio | SVG puro + CSS (recomendado) | HTML5 Canvas 'arc()' | CSS 'conic-gradient' / máscaras | GIF animado / Lottie |
|---|---|---|---|---|
| Tamaño del archivo | Muy pequeño (~2KB) | Pequeño | Pequeño | Grande (de decenas de KB a MB) |
| Escalabilidad vectorial | Escalado infinito, sin pérdida | Puede pixelarse según la resolución (DPI) | Escalado infinito | Píxeles pixelados en GIF / no aplica a Lottie |
| Carga de CPU/GPU | Muy baja (fácil de acelerar por GPU) | Carga de CPU por la computación del script | Baja | Ocupa memoria de GPU y genera alta carga de renderizado en CPU |
| Animación con CSS | Se aplica con suavidad mediante 'stroke-dashoffset' | Requiere 'requestAnimationFrame' de JS | Requiere '@property' (limitación en navegadores antiguos) | Imposible / dependiente de la librería |
| Compatibilidad con navegadores | Prácticamente todos, incluido IE | Prácticamente todos | Sobre todo navegadores modernos (soporte parcial) | Compatible con IE (Lottie solo en entornos modernos) |
5 errores habituales al crear una barra de progreso circular en SVG
- No restar la mitad del grosor del trazo al radio: en SVG, el borde se extiende hacia ambos lados a lo largo de la línea central del trazado. Si no lo restas, la mitad exterior se sale del viewBox y queda recortada.
- Omitir 'transform-origin: center' al girar -90 grados: si no defines el eje de rotación, el círculo gira tomando como referencia la coordenada 0,0 predeterminada de SVG (la esquina superior izquierda) y acaba fuera de la pantalla.
- Omitir 'stroke-linecap: round': el extremo del indicador de progreso queda plano, como cortado con un cuchillo, y da un aspecto tosco de interfaz anticuada.
- Usar un valor de pi de baja precisión (π = 3.14) escrito directamente en el código: si calculas la circunferencia de forma imprecisa, al llegar al 100 % puede aparecer una pequeña separación (gap) entre el punto de inicio y el final, o pueden solaparse. Usa 'Math.PI' de JavaScript.
- Omitir la 'transition' de CSS: cuando cambian los datos, el indicador da saltos bruscos y parece teletransportarse. Debes aplicar una transición adecuada a la propiedad del offset para conseguir una respuesta fluida.
Flujo de trabajo en 5 pasos para crear una barra de progreso circular sin fallos
- Define el tamaño y el viewBox: decide el tamaño total (por ejemplo, 100x100) y configura el SVG con 'viewBox="0 0 100 100"'.
- Calcula un radio seguro: elige el grosor del trazo (por ejemplo, 10) y aplica la fórmula r = (D − stroke) / 2 para obtener r = 45.
- Calcula la longitud de la circunferencia: usa la fórmula C = 2π r para obtener la longitud total. (2 × 3.14159 × 45 = 282.74)
- Coloca la pista de fondo y el indicador: superpón dos círculos del mismo tamaño; el de abajo será la pista de color claro y el de arriba, el indicador con el color del progreso.
- Aplica la transición CSS y el offset: calcula 'stroke-dashoffset' según la fórmula del porcentaje, insértalo como estilo en línea y completa la animación con una transición.
7 consejos para animar SVG
- Extremos redondeados: acostúmbrate a usar siempre 'stroke-linecap: round' para una interfaz moderna y cuidada.
- Relleno con degradado: en lugar de un color sólido, declara '<defs><linearGradient>' y asígnalo con 'stroke="url(#gradient)"' para crear efectos llamativos.
- Aceleración por hardware: para evitar que se pierdan fotogramas durante la animación, añade 'will-change: stroke-dashoffset' al elemento del círculo del indicador.
- Estabilidad al 100 %: asegúrate de que al 100 % el valor sea 'stroke-dashoffset: 0' para que no se produzca ningún pequeño desajuste.
- Estilo de líneas de graduación (tipo medidor): si divides 'stroke-dasharray' en segmentos de longitud y espacio (por ejemplo, '5 10'), puedes crear un indicador discontinuo como el de un tablero de automóvil en lugar de una línea continua.
- Indicador en forma de semicírculo: divide la circunferencia por la mitad, corta la parte inferior y ajusta el viewBox y la fórmula del offset a un semicírculo para lograr una interfaz tipo velocímetro.
- Aprovecha los generadores: para comprobar que el renderizado no tiene errores, en lugar de calcular a mano cada vez, usa una herramienta generadora web y prueba con controles deslizantes en tiempo real.
Árbol de decisión técnico: ¿qué enfoque te conviene?
- ¿Hay mucha interacción (visualización de datos, por ejemplo) y la animación CSS es clave? ➔ Método SVG con 'stroke-dashoffset' (recomendado)
- ¿Necesitas efectos de partículas o manipular píxeles a más de 60 fotogramas por segundo? ➔ Renderizado con HTML5 Canvas
- ¿Es un gráfico estático, no necesitas compatibilidad con IE y quieres reducir el código al mínimo? ➔ Método CSS con 'conic-gradient'
- ¿Un diseñador debe insertar gráficos animados complejos por su cuenta, sin desarrollador? ➔ Lottie / GIF animado
Glosario de términos clave (guía rápida)
- SVG (Scalable Vector Graphics): formato de gráficos vectoriales 2D que se dibuja con ecuaciones matemáticas y no se pixela por mucho que lo amplíes.
- stroke-dasharray: propiedad que define la longitud de los trazos y los espacios para dividir una línea continua en segmentos discontinuos. Aquí convierte toda la circunferencia en un único trazo discontinuo.
- stroke-dashoffset: propiedad de desplazamiento que mueve el punto donde empieza el trazo discontinuo. Se ajusta en proporción inversa al progreso para mostrar el tramo vacío que queda.
- Circunferencia (Circumference, 2πr): longitud total del borde de un círculo. Se convierte en el 100 % de la longitud de la barra de progreso.
- viewBox: área del sistema de coordenadas lógico del lienzo SVG.
- stroke-linecap: round: atributo SVG que redondea los extremos de una línea.
- transform-origin: eje central que sirve de referencia al rotar o escalar.
- Aceleración por hardware (will-change): propiedad CSS que indica al navegador que delegue en la GPU los cálculos de animación de un elemento para renderizarlo con suavidad.
Preguntas frecuentes
P1. ¿Por qué hay que restar la mitad del grosor del trazo al calcular el radio?
R1. En SVG, el trazo se reparte por igual a ambos lados de una ruta imaginaria. Si el grosor es de 10 px, crece 5 px hacia dentro y 5 px hacia fuera respecto a la línea central. Para evitar que esos 5 px exteriores se salgan del lienzo, reducimos el radio del círculo en 5 px y lo empujamos hacia dentro.
P2. ¿Se puede aplicar un degradado con varios colores que se sucedan suavemente a lo largo de un trazado circular?
R2. Sí. Dentro del SVG, usa '<defs>' y '<linearGradient>' para definir el color inicial y el final, y después haz que la propiedad stroke del círculo haga referencia al id de ese degradado ('url(#gradient-id)'). Eso sí, un degradado de tipo conic-gradient que siga el contorno del círculo es complicado en SVG 1.1; conviene combinar funciones CSS modernas.
P3. ¿Cómo hago que el indicador disminuya en sentido antihorario?
R3. Para que el indicador se vacíe en lugar de llenarse, invierte la fórmula de cálculo del offset o gira el círculo en la dirección opuesta en vez de -90 grados y ajusta la dirección del offset. La forma más sencilla es invertir la orientación con 'transform: scaleX(-1) rotate(-90deg)' para forzar un renderizado en sentido inverso.
Este artículo está adaptado de nuestro original en coreano. Leer el original en coreano