Tutorial WordPress: Estilizar el bloque de navegación por paginación de Gutenberg con CSS

Introducción

En este tutorial completo aprenderás a estilizar el bloque de paginación de Gutenberg (Query Pagination / Navigation Pagination) con CSS para obtener un aspecto consistente con tu tema, mejorar la usabilidad y mantener la accesibilidad. Cubriremos cómo identificar las clases del bloque, aplicar estilos en el frontend y en el editor, controlar estados (hover, focus, activo, deshabilitado), adaptar a móvil y RTL, y cómo añadir transiciones y controles visuales (flechas, números, pills, etc.). También verás ejemplos listos para usar y cómo añadir la hoja de estilo al tema mediante PHP.

1. Entender la estructura HTML y las clases del bloque

Antes de escribir CSS, inspecciona el bloque en el navegador (Inspector / DevTools). Gutenberg suele generar clases con prefijos wp-block-. Para la paginación dentro de un Query Loop encontrarás elementos similares a:

.wp-block-query-pagination — contenedor principal
.wp-block-query-pagination__previous y .wp-block-query-pagination__next — controles prev/next (pueden ser anchors o botones)
.wp-block-query-pagination__items — contenedor de números (si existen)
.wp-block-query-pagination__page o .wp-block-query-pagination__item — item de página
.is-active — clase aplicada a la página actual en algunos casos

Si tu instalación de WordPress o un plugin cambia la salida, usa DevTools para confirmar los selectores exactos. Los ejemplos de CSS que verás a continuación recurren a estas clases comunes ajústalos si tu HTML difiere.

2. Reglas CSS básicas para la paginación

Un punto de partida: reset de estilos y diseño horizontal centrado con espacios uniformes.

.wp-block-query-pagination {
  display: flex
  flex-wrap: wrap
  gap: 0.5rem
  justify-content: center
  align-items: center
  margin: 2rem 0
  list-style: none
  padding: 0
}
.wp-block-query-pagination a,
.wp-block-query-pagination button {
  display: inline-flex
  align-items: center
  justify-content: center
  min-width: 2.4rem
  height: 2.4rem
  padding: 0 0.6rem
  border-radius: 0.5rem
  text-decoration: none
  border: 1px solid transparent
  background: transparent
  color: inherit
  cursor: pointer
  transition: background-color 0.15s ease, color 0.15s ease, box-shadow 0.15s ease
}

3. Estilizar estados: hover, foco, activo y deshabilitado

Los estados son esenciales para usabilidad y accesibilidad. Usa :hover y :focus-visible para mostrar interacción, y .is-active o [aria-current=page] para la página actual.

/ Hover y foco accesible /
.wp-block-query-pagination a:hover,
.wp-block-query-pagination button:hover,
.wp-block-query-pagination a:focus-visible,
.wp-block-query-pagination button:focus-visible {
  background-color: #005fcc
  color: #fff
  outline: none
  box-shadow: 0 0 0 3px rgba(0, 95, 204, 0.15)
}

/ Página actual (varía según markup se usa aria-current en HTML5) /
.wp-block-query-pagination [aria-current=page],
.wp-block-query-pagination .is-active {
  background-color: #002f6c
  color: #fff
  cursor: default
  pointer-events: none
}

/ Elementos deshabilitados (por ejemplo prev/next sin enlace) /
.wp-block-query-pagination .wp-block-query-pagination__previous[aria-disabled=true],
.wp-block-query-pagination .wp-block-query-pagination__next[aria-disabled=true] {
  opacity: 0.45
  cursor: not-allowed
}

4. Diseño tipo pills y números circulares

Estilo popular: números como pastillas (pills). Aquí hay dos variantes — pill compacto y circular para páginas únicas.

/ Pills /
.wp-block-query-pagination a,
.wp-block-query-pagination button {
  border-radius: 9999px / pill /
  padding: 0.35rem 0.7rem
}

/ Circular para números /
.wp-block-query-pagination .wp-block-query-pagination__page {
  width: 2.4rem
  height: 2.4rem
  padding: 0
  display: inline-grid
  place-items: center
  border-radius: 50%
}

5. Flechas personalizadas y iconos

Puedes usar pseudo-elementos o SVG inline. Ejemplo con pseudo-elemento usando contenido Unicode o SVG como background-image.

/ Usando pseudo-elemento con flecha Unicode /
.wp-block-query-pagination .wp-block-query-pagination__previous::before,
.wp-block-query-pagination .wp-block-query-pagination__next::after {
  font-family: inherit
  font-weight: 700
  display: inline-block
  color: inherit
}
.wp-block-query-pagination .wp-block-query-pagination__previous::before { content: ◀ margin-right: 0.4rem }
.wp-block-query-pagination .wp-block-query-pagination__next::after { content: ▶ margin-left: 0.4rem }

/ Usando SVG como fondo (más control sobre tamaño y color) /
.wp-block-query-pagination .wp-block-query-pagination__previous,
.wp-block-query-pagination .wp-block-query-pagination__next {
  background-repeat: no-repeat
  background-position: center left
  padding-left: 2rem
}
.wp-block-query-pagination .wp-block-query-pagination__previous {
  background-image: url(data:image/svg xmlutf8,

6. Responsividad y diseño para pantallas pequeñas

En móvil conviene apilar o reducir espacios también se puede ocultar números y dejar solo prev/next.

@media (max-width: 640px) {
  .wp-block-query-pagination {
    gap: 0.35rem
    justify-content: center
  }

  / Opción: ocultar números y mostrar solo prev/next /
  .wp-block-query-pagination .wp-block-query-pagination__items {
    display: none
  }
}

7. Soporte RTL

Considera la orientación de flechas y la dirección del layout. Usa :dir(rtl) o selectores con [dir=rtl] para invertir el posicionamiento.

html:dir(rtl) .wp-block-query-pagination .wp-block-query-pagination__previous::before { content: ▶ margin-right: 0 margin-left: 0.4rem }
html:dir(rtl) .wp-block-query-pagination .wp-block-query-pagination__next::after { content: ◀ margin-left: 0 margin-right: 0.4rem }

8. Temas oscuros y prefers-color-scheme

Respeta los esquemas de color del usuario con la media query prefers-color-scheme.

@media (prefers-color-scheme: dark) {
  .wp-block-query-pagination a,
  .wp-block-query-pagination button {
    color: #e6eef8
    border-color: rgba(255,255,255,0.06)
  }
  .wp-block-query-pagination a:hover,
  .wp-block-query-pagination button:hover {
    background-color: rgba(255,255,255,0.07)
    color: #fff
  }
}

9. Especificidad, prioridad y cuándo usar !important

Gutenberg aplica estilos por defecto con cierta especificidad. Si tus reglas no se aplican, incrementa la especificidad usando selectores más concretos (por ejemplo añadiendo la clase del tema o el contenedor) antes de recurrir a !important. Ejemplo:

/ Mayor especificidad /
.site-content .wp-block-query-pagination a {
  background-color: #fafafa
}

/ Si no queda otra: /
.wp-block-query-pagination a {
  background-color: #fafafa !important
}

10. Añadir estilos al editor (Block Editor) para previsualizar

Para que el editor refleje los mismos estilos que el frontend, incluye una hoja de estilos para el editor. Puedes usar add_action(enqueue_block_editor_assets) o registrar editor-styles. Ejemplo de función PHP para encolar un CSS de editor:

11. Encolar la hoja de estilos en el frontend

Añade un archivo CSS para el frontend y encola en functions.php. Aquí el ejemplo:

12. Uso de theme.json y variables CSS

Si tu tema usa theme.json, registra variables globales (colores, radios) y luego utilízalas en tu CSS para mantener coherencia. Ejemplo CSS consumiendo variables:

.wp-block-query-pagination a {
  background-color: var(--wp--preset--color--background, transparent)
  color: var(--wp--preset--color--text, inherit)
  border-radius: var(--wp--border-radius, 0.5rem)
}

13. Accesibilidad: roles, labels y focus

Asegúrate de que los controles actúen como links o buttons apropiados y que el elemento actual esté marcado con aria-current=page. Mantén un foco claro con :focus-visible en lugar de solo :focus para no mostrar outline al hacer clic con ratón:

.wp-block-query-pagination a:focus-visible,
.wp-block-query-pagination button:focus-visible {
  outline: 3px solid rgba(0,123,255,0.25)
  outline-offset: 3px
}

14. Ejemplo completo (estilo moderno, centrado, pills y flechas)

Archivo CSS listo para pegar en tu tema (ajusta colores a tu paleta):

/ pagination.css - ejemplo completo /
.wp-block-query-pagination {
  display: flex
  flex-wrap: wrap
  gap: 0.5rem
  justify-content: center
  align-items: center
  margin: 1.5rem 0
  padding: 0
}
.wp-block-query-pagination a,
.wp-block-query-pagination button {
  display: inline-flex
  align-items: center
  justify-content: center
  min-width: 2.4rem
  height: 2.4rem
  padding: 0 0.65rem
  border-radius: 9999px
  background: #f3f6fb
  color: #0b2b4a
  border: 1px solid transparent
  text-decoration: none
  font-weight: 600
  transition: background-color 0.12s ease, transform 0.08s ease, box-shadow 0.12s ease
}
.wp-block-query-pagination a:hover,
.wp-block-query-pagination button:hover {
  background: #e2efff
  transform: translateY(-1px)
}
.wp-block-query-pagination [aria-current=page],
.wp-block-query-pagination .is-active {
  background: #0b63d6
  color: #ffffff
  box-shadow: 0 2px 8px rgba(11,99,214,0.18)
  pointer-events: none
}
.wp-block-query-pagination .wp-block-query-pagination__previous::before { content: ◀ margin-right: 0.45rem }
.wp-block-query-pagination .wp-block-query-pagination__next::after { content: ▶ margin-left: 0.45rem }

/ Mobile: reducir paddings /
@media (max-width: 540px) {
  .wp-block-query-pagination a,
  .wp-block-query-pagination button {
    min-width: 2.1rem
    height: 2.1rem
    padding: 0 0.45rem
    font-size: 0.92rem
  }
  .wp-block-query-pagination .wp-block-query-pagination__items { display: none } / opcional /
}

15. Consejos finales y buenas prácticas

Inspecciona siempre el HTML generado por tu versión de Gutenberg y ajusta selectores.
Evita usar !important salvo necesidad incrementa especificidad primero.
Encola estilos del editor para una vista consistente durante la edición.
Prueba el enfoque con teclado y lectores de pantalla: asegúrate de que aria-current y foco sean claros.
Usa variables CSS (o theme.json) para mantener coherencia de diseño y facilitar cambios globales.
Considera animaciones sutiles y transiciones, pero evita exceso que distraiga.

Resumen

Estilizar el bloque de paginación de Gutenberg requiere identificar las clases generadas, diseñar estados (hover, focus, activo), proporcionar estilos responsivos y asegurarse de que el editor y el frontend compartan las mismas reglas. Con los ejemplos anteriores tendrás plantillas reutilizables para adaptar la paginación a tu tema y mantener una buena experiencia de usuario y accesibilidad.

SushiHost