Hapio ist „headless“. Wir stellen Ihnen die Buchungs- und Terminplanungs-API zur Verfügung – Dienstleistungen, Ressourcen, Zeitpläne, buchbare Termine – und Sie gestalten das Erlebnis, das Ihre Kunden sehen. Das funktioniert gut für den Buchungsablauf selbst, aber früher oder später benötigen die meisten Projekte einen echten Kalender: eine Wochenansicht, in der Mitarbeiter Buchungen verschieben können, eine Tagesansicht, die freie Termine anzeigt, und eine Monatsansicht für den Überblick.

Bislang bedeutete das, dass man entweder auf eine kommerzielle Kalenderbibliothek zurückgreifen oder eine eigene von Grund auf neu erstellen musste. Keine der beiden Optionen ist ideal, wenn Ihr Datenmodell bereits in Hapio vorliegt.

Heute veröffentlichen wir Hapio Calendar, eine Open-Source-Kalenderkomponente in voller Größe für React 19 und shadcn/ui. Sie umfasst Wochen-, Tages-, Monats- und Listenansichten, Drag-and-Drop- und Größenanpassungsfunktionen, kalenderbezogene Zeitzonen und wiederkehrende Termine und ist so konzipiert, dass sie von Haus aus mit der Hapio-API kommunizieren kann. Sie steht unter der MIT-Lizenz, und es gibt keine Premium-Variante.

Die Wochenansicht. Die Öffnungszeiten sind schattiert, Termine sind im Raster eingezeichnet, und die rote Linie markiert die aktuelle Uhrzeit.

Was es bewirkt

Hapio Calendar ist ein vollwertiger Kalender und keine Datumsauswahl. Standardmäßig bietet er Ihnen:

• Vier Ansichten: Woche, Tag, Monat und Liste. Die Ansicht und das Datum können optional in der URL gespeichert werden, sodass Links geteilt werden können.
• Ziehen, Größe ändern und Bearbeitung über die Tastatur. Termine können mit der Maus verschoben und in ihrer Größe angepasst werden oder über ein Aktionsmenü, das bei jedem Termin verfügbar ist, mithilfe der Tastatur. Sie können Elemente auch von außerhalb des Kalenders hineinziehen, beispielsweise aus einer Liste nicht zugewiesener Buchungen.
• Zeitzonen sind korrekt umgesetzt. Jeder Kalender verfügt über eine eigene Zeitzone, und Sie können diese wechseln, ohne den Kalender neu einzubinden. Tage mit 23 oder 25 Stunden werden korrekt dargestellt, sodass die Umstellung auf Sommerzeit das Raster nicht durcheinanderbringt.
• Buchungsregeln. Öffnungszeiten, Überschneidungsprüfungen und Ihre eigenen benutzerdefinierten Prüfungen. Wenn eine Buchung abgelehnt wird, teilt der Kalender dem Benutzer den Grund dafür mit.
• Optimistisches Speichern. Eine Änderung wird sofort angezeigt, befindet sich im Status „Ausstehend“, während Ihre API sie speichert, und wird rückgängig gemacht, falls das Speichern fehlschlägt.
• Wiederkehrende Ereignisse. Bearbeitung gemäß RFC 5545, einschließlich serverseitiger Erweiterung, wenn der Server die Zeitzone und das Datum kennt.
• Integrierte Barrierefreiheit. Tastaturnavigation, Live-Ansagen und Axe-Checks bei jedem Beispiel.
• Lokalisierung. Mehrere Sprachen, darunter Schwedisch, sowie Layouts mit Schreibrichtung von rechts nach links.
• Server-Rendering. Funktioniert mit SSR und React Server Components und enthält einen Leitfaden zur Content Security Policy.

Die Monatsansicht mit ISO-Wochennummern, mehrtägigen Veranstaltungen und einer Überlaufanzeige „+N weitere“ an Tagen mit vielen Einträgen.

Entwickelt für Hapio

Der Kalender ist eine generische Komponente, wurde jedoch speziell auf die Funktionsweise eines Hapio-Projekts zugeschnitten. Die Integration basiert im Wesentlichen auf drei Callbacks:

1. Laden. Eine Ereignisquelle ruft für jeden sichtbaren Datumsbereich Buchungen aus einer Route auf Ihrem Server ab.
2. Buchung. Buchbare Zeitfenster von Hapio werden als freie Zeiten angezeigt. Wenn ein Kunde oder Mitarbeiter eines davon auswählt, erstellt Ihre App die Buchung.
3. Termin verschieben. Aufruf von Drag- und Tastaturbefehlen onEventChange. Wenn Hapio die Änderung ablehnt – die Ressource ist nicht verfügbar, der Termin liegt außerhalb der Öffnungszeiten –, macht der Kalender die Änderung rückgängig und zeigt den Grund an.

Eine Buchung durch Ziehen verschieben. Der ursprüngliche Termin bleibt ausgegraut, bis Ihr Server die Änderung bestätigt.

Genau wie bei unserem Admin-Panel gelangt Ihr API-Token niemals in den Browser. Ihr Server kommuniziert mit Hapio über die hapio-sdk Paket, und der Kalender kommuniziert ausschließlich mit Ihrem Server. Die Berechtigungen für das Token werden wie gewohnt von Hapio durchgesetzt.

Der Code gehört dir

Wir wollten nicht einfach nur einen weiteren „Black-Box“-Kalender auf den Markt bringen. Der Hapio-Kalender ist in drei Ebenen unterteilt, und Sie entscheiden selbst, wie tief Sie in die Details einsteigen möchten:

• @hapio/calendar-core — die framework-unabhängige Logik: Layout, Zeitzonenberechnung, Regeln, Wiederholung. Kein React.
• @hapio/calendar-react — Headless-Hooks auf dem Core. Bringen Sie Ihr eigenes Markup und Styling mit.
• Die @hapio shadcn-Registrierung — die formatierte, einsatzbereite Komponente. Sie wird mit der shadcn-Befehlszeilenschnittstelle installiert und in dein Projekt, daher können Sie die Dateien wie jede andere ShadCN-Komponente bearbeiten.

Die meisten Projekte beginnen mit der Registrierungs-Komponente und greifen erst dann auf die Hooks zurück, wenn sie etwas Ungewöhnliches benötigen. So oder so gibt es nichts, was Sie nicht ändern könnten.

Erste Schritte

Sie benötigen React 19.2 oder höher sowie eine shadcn/ui-App auf Basis von Tailwind CSS 4 (entweder mit der Radix- oder der Base-UI-Basis). Für das Server-Rendering ist Node 22.12 oder höher erforderlich.

Fügen Sie zunächst das @hapio Registrierung bei Ihrem components.json:

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

Fügen Sie anschließend den Kalender hinzu:

npx shadcn@latest add @hapio/hapio-calendar

Dadurch wird die Komponente in components/hapio-calendar/, zieht den Shadcn ein button, popover und scroll-area Komponenten und installiert @hapio/calendar-react und temporal-polyfill. Laden Sie das Polyfill einmalig an der obersten Ebene Ihrer App und rendern Sie anschließend den Kalender mit einer Höhe und einer Zeitzone:

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

Die Basiskomponente ist schreibgeschützt. Hinzufügen calendar-selection damit die Nutzer Zeiten auswählen können, calendar-editing um Ereignisse zu verschieben und ihre Größe anzupassen, und calendar-external-draggable um Gegenstände von außen hineinzulegen. Das Installationsanleitung führt durch jeden einzelnen Schritt und Dein erster Kalender übernimmt es von dort an.

Hapio Calendar wurde mit React 19, shadcn/ui, TypeScript, Tailwind CSS und dem Temporal-Polyfill entwickelt und unter der MIT-Lizenz veröffentlicht. Jedes Beispiel durchläuft automatisierte Barrierefreiheitsprüfungen, und die Testsuite ist im Quellcode enthalten. Issues und Pull-Requests sind herzlich willkommen.

Durchsuchen Sie die Beispiele, lies den Dokumente, oder führen Sie Folgendes aus: npx shadcn@latest add @hapio/hapio-calendar und probieren Sie es noch heute in Ihrem eigenen Projekt aus.

Links: calendar.hapio.io · GitHub-Repository · Hapio-Dokumentation · Hapio-Portal