useAvailability

Overview

useAvailability performs a debounced search for available rooms matching the given filters. It calls GET {apiUrl}/availability with query parameters.

import { useAvailability } from '@roomkit/react';

Usage

function RoomFinder() {
    const { data, isLoading, error, refetch } = useAvailability({
        filters: {
            timeRange: {
                startsAt: new Date('2026-03-02T10:00:00Z'),
                endsAt: new Date('2026-03-02T12:00:00Z'),
            },
            minCapacity: 30,
            capacityType: 'seated',
            requiredEquipment: ['projector'],
        },
        pagination: { limit: 10 },
        debounceMs: 300,
    });

    if (isLoading) return <div>Searching...</div>;
    if (error) return <div>Error: {error.message}</div>;

    return (
        <ul>
            {data?.items.map((item) => (
                <li key={item.room.id}>
                    {item.room.id} — Score: {item.score.toFixed(2)}
                </li>
            ))}
        </ul>
    );
}

UseAvailabilityOptions

interface UseAvailabilityOptions {
    filters: AvailabilityFilter;
    pagination?: Pagination;
    debounceMs?: number;
    onSuccess?: (data: AvailabilityResult) => void;
    onError?: (error: Error) => void;
}

Option	Type	Required	Description
`filters`	`AvailabilityFilter`	Yes	Search filters (time range, capacity, equipment, etc.)
`pagination`	`Pagination`	No	Cursor-based pagination (`{ cursor?, limit }`)
`debounceMs`	`number`	No	Debounce delay in milliseconds (default: `300`)
`onSuccess`	`(data) => void`	No	Called when the request succeeds
`onError`	`(error) => void`	No	Called when the request fails

AvailabilityFilter

interface AvailabilityFilter {
    timeRange: { startsAt: Date; endsAt: Date };
    minCapacity?: number;
    capacityType?: 'seated' | 'exam' | 'standing';
    requiredEquipment?: string[];
    requiredAccessibility?: string[];
    locationScope?: string;
    excludeRoomIds?: string[];
}

Return Value

{ data: AvailabilityResult | null; isLoading: boolean; error: Error | null; refetch: () => Promise<void> }

Field	Type	Description
`data`	`AvailabilityResult \| null`	Search results with scored rooms
`isLoading`	`boolean`	`true` while the request is in flight
`error`	`Error \| null`	The error if the request failed
`refetch`	`() => Promise<void>`	Manually re-fetch the data

API Endpoint

GET {apiUrl}/availability?startsAt=...&endsAt=...&minCapacity=...&capacityType=...&requiredEquipment=...

Query parameters are only included when the corresponding filter is provided. The request is automatically aborted if filters change before the previous request completes.