@nylas/components-availability

Nylas Availability -- In Development

Nylas Availability (<nylas-availability>) is part of the Nylas Components library that lets you build event/calendar applications in minutes. Use Nylas Availability with your Nylas account or by passing in your own JSON data.

Nylas Availability is currently in active development. Want to contribute? Find out how!

• Nylas Availability -- In Development
  • Getting Started
  • Documentation
  • Installation
  • Usage
    • Using Nylas Provider
    • Bring your own data
  • Reference
    • Properties
    • Events
    • Types

Getting Started

• Create a Nylas Developer Account

• Nylas Components

Documentation

• Nylas Availability reference

• Examples

Installation

First, install the Nylas Availability Component with npm

npm install @nylas/components-availability

or with yarn

yarn add @nylas/components-availability

or using the CDN by adding this script tag

<script src="https://unpkg.com/@nylas/components-availability"></script>

Usage

If you've installed Nylas Availability using the CDN, then <nylas-availability></nylas-availability> is ready to use.

Otherwise, import the Nylas Availability component into your application.

import "@nylas/components-availability";

Using Nylas Provider

Setup

If you haven't registered for a Nylas account yet, you can do so at dashboard.nylas.com. Once there, head to the Components tab and create a new Availability component.

Allowed domains

During the setup process, you'll be prompted to provide a list of allowed domains. Be sure to add any domains you'll be testing your app on, including localhost, and any staging and production URLs you might use.

Bring your own data

Nylas Availability can be used as a UI for any calendar data you provide.

Properties you can pass to Nylas Availability are calendars, opening_hours

Reference

Properties

Name	Type	Description	Required	Default Value
id	string	The id of the Availability component	true
access_token	string	Authorization for calendar queries	false
view_as	AvailabilityView	Display availability as list or calendar.	false	"schedule"
show_header	boolean	Toggles legend display.	false	true
date_format	DateFormat	Set the format of the date in the legend to show full date, day of the month, or day of the week.	false	"full"
busy_color	string	Customize the color of busy time slots in the legend and ticks in schedule view.	false	"#EE3248cc"
closed_color	string	Customize the color of closed time slots in the legend and ticks in schedule view.	false	"#EE3248cc"
free_color	string	Customize the color of available time slots in the legend and ticks in schedule view.	false	"#078351cc"
partial_color	string	Customize the color of partially available time slots in the legend and ticks in schedule view.	false	"#FECA7Ccc"
selected_color	string	Customize the color of busy time slots in the legend and ticks in schedule view.	false	"#002db4"
show_as_week	boolean	Display component fixed length week.	false	false
show_weekends	boolean	Controls whether or not to include weekends when using show_as_week.	false	true
show_ticks	boolean	Display time of day.	false	true
dates_to_show	number	Controls how many days to show. The actual number of days show may be less as the application will display the number of days that fit comfortably on the screen up to dates_to_show. When show_as_week is enabled, dates_to_show is not considered.	false	1
show_hosts	HostView	Toggles hosts display.	false	"show"
allow_date_change	boolean	Controls if the date can be changed. When set to true, the user can not change the day. When set to false, the Availability component is fixed to today's date or start_date if passed.	false	true
attendees_to_show	number	Truncates the number of attendees shown	false	5
start_date	Date	Start availability component on a specific date. Used in combination with dates_to_show = 1 to display availability for one day only.	false	new Date()
start_hour	number	Controls the start time of each day.	false	0
end_hour	number	Controls the end time for each day.	false	24
slot_size	number	Set the size of each time block in minutes.	false	15
open_hours	AvailabilityRule[]	Set a schedule through out the week that show as available or busy regardless of calendar availability.	false	[]
events	EventDefinition[]	TODO	false	[]
calendars	Calendar[]	TODO	false	[]
participants	string[]	Set the participants to check availability for each time slot.	false	[]
required_participants	string[]	Set the participants who must be available for each time slot.	false	[]
timezone	string	Configure the viewing timezone for ticks and slot sizes.	false	""
event_buffer	number	TODO: Time in minutes to add before and after each time slot.	false	0
capacity	number	TODO: Group events? Unused	false	?
allow_booking	boolean	Controls if time slots are bookable when used with the Nylas Booking component.	false	false
booking_user_email	string	TODO?	false	false
booking_user_token	string	TODO?	false	false
mandate_top_of_hour	boolean	Sets selected slots to the start of the hour. When false, slots can be selected at 15 minute intervals.	false	false
max_bookable_slots	number	The maximum number of slots that can be selected.	false	1
max_book_ahead_days	number	The maximum number of days in the future an event can be selected.	false	30
min_book_ahead_days	number	The minimum number of days in the future an event can be selected. Or the number days in advance required for an event to be selected.	false	0
overbooked_threshold	number	TODO	false	100
partial_bookable_ratio	number	TODO	false	0.01

Events

You can listen to certain events from your application by adding an event listener to the component.

onError Listen to error events.

document
  .querySelector("nylas-availability")
  .addEventListener("onError", (event) => {
    let { detail } = event;
    console.log("onError: ", detail);
  });

timeSlotChosen Listen to timeSlotChosen event. Responds with an list of SelectableSlots.

document
  .querySelector("nylas-availability")
  .addEventListener("timeSlotChosen", (event) => {
    let { detail } = event;
    console.log("timeSlotChosen: ", detail.timeSlots);
  });

eventOptionsReady

document
  .querySelector("nylas-availability")
  .addEventListener("eventOptionsReady", (event) => {
    let { detail } = event;
    console.log("eventOptionsReady: ", detail.slots);
  });

Types

type DateFormat: "full" | "date"| "weekday" | "none";

type AvailabilityView: "schedule"| "list";

type HostView: "show" | "hide";

interface TimeSlot {
  start_time: Date;
  end_time: Date;
  available_calendars: string[];
  calendar_id?: string;
  expirySelection?: string;
  recurrence_cadence?: string;
  recurrence_expiry?: Date | string;
  isBookable: boolean;
}

interface SelectableSlot extends TimeSlot {
  selectionStatus: SelectionStatus;
  availability: AvailabilityStatus;
  selectionPending?: boolean;
  hovering?: boolean;
  timezone?: string;
}