Hapio es una plataforma «headless». Te proporcionamos la API de reservas y programación —servicios, recursos, horarios, franjas horarias reservables— y tú creas la experiencia que ven tus clientes. Esto funciona bien para el proceso de reserva en sí, pero tarde o temprano la mayoría de los proyectos necesitan un calendario real: una vista semanal en la que el personal pueda arrastrar y soltar las reservas, una vista diaria que muestre dónde están las franjas horarias disponibles y una vista mensual para tener una visión general.

Hasta ahora, eso significaba recurrir a una biblioteca de calendarios comercial o crear una desde cero. Ninguna de las dos opciones es la ideal cuando tu modelo de datos ya está en Hapio.

Hoy lanzamos Hapio Calendar, un componente de calendario de código abierto y tamaño completo para React 19 y shadcn/ui. Incluye vistas semanal, diaria, mensual y de lista; permite arrastrar y cambiar el tamaño; ofrece zonas horarias específicas para cada calendario y eventos recurrentes, y está diseñado para interactuar con la API de Hapio desde el primer momento. Cuenta con licencia MIT y no hay ningún nivel premium.

Vista semanal. Los horarios de apertura aparecen sombreados, las reservas se muestran en la cuadrícula y la línea roja marca la hora actual.

Para qué sirve

Hapio Calendar es un calendario completo, no un selector de fechas. De serie, te ofrece:

• Cuatro vistas: semanal, diaria, mensual y de lista, con la opción de incluir la vista y la fecha en la URL para que los enlaces se puedan compartir.
• Arrastrar, cambiar el tamaño y editar con el teclado. Los eventos se pueden mover y cambiar de tamaño con el ratón o con el teclado a través de un menú de acciones que aparece en cada evento. También puedes arrastrar elementos desde fuera del calendario, por ejemplo, desde una lista de reservas sin asignar.
• Las zonas horarias están bien configuradas. Cada calendario tiene su propia zona horaria y puedes cambiarla sin necesidad de volver a montarlo. Los días de 23 o 25 horas se muestran correctamente, por lo que los cambios de horario de verano no alteran la cuadrícula.
• Normas de reserva. Horario de apertura, comprobaciones de solapamientos y tus propias comprobaciones personalizadas. Cuando se rechaza una reserva, el calendario indica al usuario el motivo.
• Guardados provisionales. Los cambios se muestran de inmediato, permanecen en estado pendiente mientras la API los guarda y se revierten si el proceso de guardado falla.
• Eventos recurrentes. Edición según la serie RFC 5545, incluida la expansión del lado del servidor cuando este conoce la zona y la fecha.
• Accesibilidad integrada. Desplazamiento mediante el teclado, anuncios en tiempo real y comprobaciones de «axe» en cada ejemplo.
• Localización. Varios idiomas, incluido el sueco, y diseños de escritura de derecha a izquierda.
• Renderización en el servidor. Funciona con SSR y los componentes de servidor de React, e incluye una guía sobre la Política de Seguridad de Contenidos.

La vista mensual, con los números de semana ISO, eventos de varios días y un indicador de «+N más» en los días con mucha actividad.

Creado para Hapio

El calendario es un componente genérico, pero se ha diseñado teniendo en cuenta el funcionamiento real de un proyecto de Hapio. La integración se reduce a tres funciones de devolución de llamada:

1. Carga. Una fuente de eventos recupera las reservas correspondientes a cada intervalo de fechas visible a partir de una ruta en tu servidor.
2. Reserva. Las franjas horarias disponibles de Hapio se muestran como «horario libre». Cuando un cliente o un miembro del personal selecciona una de ellas, tu aplicación crea la reserva.
3. Cambiar la fecha. Llamada de arrastres y movimientos con el teclado onEventChange. Si Hapio rechaza el cambio —el recurso no está disponible, la franja horaria queda fuera del horario de apertura—, el calendario lo revoca y muestra el motivo.

Cómo cambiar la fecha de una reserva arrastrándola. La franja horaria original permanecerá desactivada hasta que tu servidor confirme el cambio.

Al igual que en nuestro panel de administración, tu token de API nunca llega al navegador. Tu servidor se comunica con Hapio a través de la hapio-sdk paquete, y el calendario solo se comunica con tu servidor. Hapio se encarga de gestionar los permisos del token, como de costumbre.

El código te pertenece

No queríamos lanzar otro calendario tipo «caja negra». Hapio Calendar se divide en tres niveles, y tú eliges hasta dónde quieres profundizar:

• @hapio/calendar-core — La lógica sin framework: diseño, cálculos de husos horarios, reglas, recurrencia. Sin React.
• @hapio/calendar-react — Ganchos «headless» sobre el núcleo. Trae tu propio marcado y estilo.
• El @hapio registro de shadcn — el componente con estilo y listo para usar. Se instala mediante la CLI de shadcn y se copia en tu proyecto, por lo que puedes editar los archivos como cualquier otro componente de shadcn.

La mayoría de los proyectos empezarán por el componente de registro y solo recurrirán a los hooks si necesitan algo fuera de lo habitual. En cualquier caso, no hay nada que no se pueda modificar.

Cómo empezar

Necesitas React 19.2 o posterior y una aplicación shadcn/ui basada en Tailwind CSS 4 (ya sea con la base Radix o Base UI). Para el renderizado en servidor, Node 22.12 o posterior.

En primer lugar, añade el @hapio registro en tu components.json:

{
  "registries": {
    "@hapio": "https://calendar.hapio.io/r/{name}.json"
  }
}

A continuación, añade el calendario:

npx shadcn@latest add @hapio/hapio-calendar

Esto copia el componente en components/hapio-calendar/, recoge el shadcn button, popover y scroll-area componentes e instalaciones @hapio/calendar-react y temporal-polyfill. Carga el polyfill una vez en la raíz de tu aplicación y, a continuación, muestra el calendario indicando una altura y una zona horaria:

<HapioCalendar
  events={events}
  timeZone="Europe/Stockholm"
  className="h-[36rem]"
/>

El componente base es de solo lectura. Añadir calendar-selection para que los usuarios puedan elegir horarios, calendar-editing para mover y cambiar el tamaño de los eventos, y calendar-external-draggable para introducir objetos desde el exterior. El guía de instalación explica cada paso uno por uno, y Tu primer calendario y a partir de ahí se encarga él.

Hapio Calendar está desarrollado con React 19, shadcn/ui, TypeScript, Tailwind CSS y el polyfill de Temporal, y se distribuye bajo la licencia MIT. Todos los ejemplos se someten a comprobaciones automáticas de accesibilidad, y el conjunto de pruebas se incluye con el código fuente. Se agradecen mucho las incidencias y las solicitudes de incorporación de cambios.

Explora el ejemplos, lee el documentos, o bien ejecutar npx shadcn@latest add @hapio/hapio-calendar y pruébalo hoy mismo en tu propio proyecto.

Enlaces: calendar.hapio.io · Repositorio de GitHub · Documentación de Hapio · Portal de Hapio