Getting Started
Learn the core concepts and build your first availability flow.
Getting Started
Core concepts
- Weekly schedule — Your default availability (e.g. Mon–Fri 9–5 in
Europe/London). - Date override — Optional custom availability for a specific date (split shift, day off, etc.).
- Bookings — Existing events in UTC; slots overlapping them are marked unavailable.
- Viewer timezone — The timezone in which you want slots returned (e.g. the user's local timezone).
Availability windows vs. time slots
getAvailabilityWindow— Returns raw time ranges for a day (e.g.[{ start: '09:00', end: '17:00' }]). Use when you need the overall availability shape.getAvailableTimeslots— Returns discrete slots (e.g. 30-minute blocks) withisAvailableflags. Use for a booking UI where users pick a slot.
Basic flow
1. Define your weekly schedule
import { DAY_OF_WEEK, type WeeklySchedule } from 'availability-js';
const weeklySchedule: WeeklySchedule = {
schedule: [
{ dayOfWeek: DAY_OF_WEEK.Monday, start: '09:00', end: '17:00' },
{ dayOfWeek: DAY_OF_WEEK.Wednesday, start: '09:00', end: '17:00' },
],
timezone: 'Europe/London',
};2. Get availability for a date
import { getAvailabilityWindow } from 'availability-js';
const windows = getAvailabilityWindow({
weeklySchedule,
date: new Date('2024-12-09'),
timezone: 'Europe/London',
});
// → [{ start: '09:00', end: '17:00' }]3. Get bookable time slots (with optional bookings)
import { getAvailableTimeslots } from 'availability-js';
const slots = getAvailableTimeslots({
weeklySchedule,
date: new Date('2024-12-09'),
timezone: 'Europe/London',
slotDurationMinutes: 30,
bookings: [
{ startTime: '2024-12-09T10:00:00Z', endTime: '2024-12-09T11:00:00Z' },
],
});
// → Example (partial):
// [
// { start: '09:00', end: '09:30', isAvailable: true },
// { start: '09:30', end: '10:00', isAvailable: true },
// { start: '10:00', end: '10:30', isAvailable: false }, // overlaps booking
// { start: '10:30', end: '11:00', isAvailable: false }, // overlaps booking
// { start: '11:00', end: '11:30', isAvailable: true },
// ...
// ]Next steps
- Working hours & overrides — Configure schedules and date exceptions
- Bookings — Exclude existing events from availability
- API Reference — Full API details
Interactive playground
Adjust schedules, dates, viewer timezones, and bookings to see live results from getAvailabilityWindow and getAvailableTimeslots.
Mode
Result
10:00–10:30 available 10:30–11:00 available 11:00–11:30 available 11:30–12:00 available 12:00–12:30 available 12:30–13:00 available 13:00–13:30 unavailable 13:30–14:00 unavailable 14:00–14:30 available 14:30–15:00 available 15:00–15:30 available 15:30–16:00 available 16:00–16:30 available 16:30–17:00 available 17:00–17:30 available 17:30–18:00 available