Availability Calendar for Website Booking

Booking Availability Calendar Implementation

Availability calendar is the central UI element of booking system. Shows which dates are open for booking, which are occupied, which are blocked. Correct display determines user experience and number of erroneous bookings.

Availability Logic

Slot availability determined by intersection of multiple sources:

interface AvailabilitySlot {
  datetime:  Date;
  available: boolean;
  reason?:   'booked' | 'blocked' | 'outside_hours' | 'capacity_full';
  capacity?: number;    // for group booking
  remaining?: number;
}

class AvailabilityService {
  async getAvailability(resourceId: number, from: Date, to: Date): Promise<AvailabilitySlot[]> {
    const [schedule, bookings, blocks] = await Promise.all([
      this.getWorkingSchedule(resourceId),  // working hours
      this.getBookings(resourceId, from, to),
      this.getBlocks(resourceId, from, to), // manual blocks
    ]);

    return this.generateSlots(from, to, schedule, bookings, blocks);
  }
}

Calendar Component (React)

import { useState } from 'react';
import { useQuery } from '@tanstack/react-query';
import { startOfMonth, endOfMonth, eachDayOfInterval, format, isSameDay } from 'date-fns';
import { enUS } from 'date-fns/locale';

interface DayAvailability {
  date:      string;
  hasSlots:  boolean;
  allBooked: boolean;
}

export function AvailabilityCalendar({ resourceId, onDateSelect }: Props) {
  const [currentMonth, setCurrentMonth] = useState(new Date());

  const { data: availability } = useQuery({
    queryKey: ['availability', resourceId, format(currentMonth, 'yyyy-MM')],
    queryFn:  () => fetchMonthAvailability(resourceId, currentMonth),
    staleTime: 60_000,
  });

  const days = eachDayOfInterval({
    start: startOfMonth(currentMonth),
    end:   endOfMonth(currentMonth),
  });

  return (
    <div className="grid grid-cols-7 gap-1">
      {/* Day of week headers */}
      {['Mon','Tue','Wed','Thu','Fri','Sat','Sun'].map(d => (
        <div key={d} className="text-center text-xs text-gray-500 py-2">{d}</div>
      ))}

      {/* Days of month */}
      {days.map(day => {
        const dateStr  = format(day, 'yyyy-MM-dd');
        const dayData  = availability?.find(a => a.date === dateStr);
        const isToday  = isSameDay(day, new Date());

        return (
          <button
            key={dateStr}
            disabled={!dayData?.hasSlots || dayData?.allBooked}
            onClick={() => onDateSelect(day)}
            className={cn(
              'aspect-square rounded-lg text-sm font-medium transition-colors',
              isToday && 'ring-2 ring-blue-500',
              dayData?.hasSlots && !dayData?.allBooked
                ? 'bg-green-50 text-green-700 hover:bg-green-100'
                : 'bg-gray-50 text-gray-300 cursor-not-allowed'
            )}
          >
            {format(day, 'd')}
          </button>
        );
      })}
    </div>
  );
}

Loading Optimization

Availability loads monthly and caches for 60 seconds. On date selection, time slots for specific day load. Cache invalidation via WebSocket event when new booking created.

Syncing Multiple Resources

For services with multiple specialists/rooms — select specific resource or show first available slot across all:

async function getFirstAvailableSlot(date: Date, serviceId: number): Promise<Slot | null> {
  const resources = await getServiceResources(serviceId);
  const slots = await Promise.all(
    resources.map(r => getAvailableSlots(r.id, date))
  );
  return slots.flat().sort((a, b) => a.datetime - b.datetime)[0] ?? null;
}

Timeframe

Availability calendar with API and component: 4–6 working days.