Only show these results:

Agenda Component

Use the Nylas Agenda Component to display calendar data. Without needing to write a single line of code, the Agenda Component comes with:

  • Theme options
  • Ability to change display date
  • Events listed with time, event title, location, and description
  • Event details are expanded on click
  • Display multiple calendars
Nylas Agenda

Prerequisites

  • A Nylas account
  • Create a new application or use an existing application with at least 1 account added.
  • An application to add the Component to.

Quickstart

The quickstart uses plain HTML and the script tag method of installation.

  1. Create a Component in your Nylas Dashboard.
  2. Copy the agenda_id.
  3. Replace the agenda_id in the sandbox below.

Quickstart Sandbox

Agenda Installation Options

You can install Agenda in 2 ways:

npm Package

  1. Run npm i @nylas/components-agenda or yarn add @nylas/components-agenda.
  2. Then import and render the component.
    // Import the web component
import '@nylas/components-agena`;

// In render method
<nylas-agenda></nylas-agenda>

Script Tag

Use the CDN script tag, https://unpkg.com/@nylas/components-agenda.

    <head>
<!-- Import the script from CDN -->
<script src="https://unpkg.com/@nylas/components-agenda"></script>
</head>
<body>
<!-- Place the component on the page -->
<nylas-agenda></nylas-agenda>
</body>

Ways to Use Agenda

Use Agenda Component with Nylas Data

You'll learn how to use your Nylas accounts with the Agenda Component.

Create the Agenda Component

  1. Log in to your Nylas dashboard.
  2. Click Components > Agenda
  3. Name your Component and select the account. To quickly start testing your Component select Enable for a single account.
    1. To learn how to enable components for multiple accounts see Authorizing Components
  4. Use an existing access token or generate a new one.
  5. Enter the domain the component will run on. Without the domains, the component will not run
    1. To run on localhost, enter an asterisk. *. Remember to change this before going to production.
  6. Save your new component.
  7. On the Edit page, you can configure your component behavior and appearance.

Generate an Access Token

Generating a new access token will not replace your existing access token; it will create a second access token with the same scopes as the previous token. You can revoke access tokens at any time.

Create a New Component

Add the Component To Your Application

  1. On the Edit page, there are instructions for installing the new component.
  2. If you haven't installed the Agenda Component already, open a terminal and run npm i @nylas/components-agenda.
  3. Then add your Nylas component. Copy and paste your component code into your application.
    <nylas-agenda id="your-component-id" calendar_id="your-calendar-id></nylas-agenda>
  4. You should refresh your application if needed. Any configuration options set on the editing page will apply to your Component.

Copy Agenda Component

If you want to get started without installing the components in your application, fork this CodeSanbox and replace the ID with your Agenda ID. The application uses demo data. Create a new Component when you're ready to use your data.

Agenda Height

When adding an Agenda component, it takes on the height of the parent container.
If your agenda isn't showing, try adding it to a div with the height specified.

<div class="app" style="height:800px">
<nylas-agenda id="3a3605a4-6d8c-49d4-8e79-0e417ac7483b" > </nylas-agenda>
</div>

Agenda Sample Code

Use Agenda Component with External Data

You'll learn how to pass in an events array and display an agenda within your application.

  1. Install the Nylas Agenda Component. npm i @nylas/components-agenda.

The Nylas Agenda Component can accept an array of objects for events. You can pass in any event data from our events endpoint. In this example, we are passing the data needed to create an event. The data input should match the formatting of the Nylas Events Object.

  import Agenda from "@nylas/components-agenda";
const staticEvents = [
{
title: "Some event that I am manipulating outside of the context of Nylas",
description: "Passed in from HTML!",
participants: [],
when: { end_time: 1600444800, object: "timespan", start_time: 1600438500 }
},
{
title: "Some I got from elsewhere",
description: "Passed in from HTML!",
participants: [],
when: { end_time: 1600449999, object: "timespan", start_time: 1600448500 }
},
{
title: "A third event of the day",
description: "Passed in from HTML!",
participants: [],
when: { end_time: 1600468500, object: "timespan", start_time: 1600458500 }
}
];
</script>

<main>
<h1>Nylas Agenda</h1>
<nylas-agenda events={staticEvents}/>
</main>
  1. Add the event data to your nylas-agenda. <nylas-agenda events={staticEvents}/>.

Congratulations!

You've created an Agenda in your application.

Agenda External Data Example

If you want to get started quickly, grab a copy of our CodeSanbox to get started. The application uses demo data. Create a new Component when you're ready to use your data.

Authorizing Components

With components, you can authorize them to work with a single account or multiple accounts.

Enable for a Single Account

A single account is a way to get started quickly. If you use this method in production, you'll have to authenticate each account from the dashboard one by one.

Enable components single account

Enable for All Accounts

To enable all accounts, you'll need to pass in a user's access token as a property of the component. One way to achieve this is to create a login screen, capture the access token and pass it into the component. You can pass in access_tokens directly in the Component.

<nylas-agenda id="COMPONENT-ID" access_token="USER-ACCESS-TOKEN"/>

Make sure to keep access_tokens hidden and never expose them online.

Enable Components for all accounts

Dashboard Preview

Dashboard previews do not work when enabling for all accounts.

Customization

Nylas components are flexible and can be customized for your needs. You can customize the display in 2 ways:

The options are the same for both the application and dashboard. The names are slightly different, and the application requires a few more options.

Nylas Dashboard Display Options

Customize the display by going to your application > Components. Then select the Component you want to edit. When you are making changes in the dashboard, the display of the Component will update.

Name Description
Allowed Domains Use glob patterns to match allowed domains
Theme Set the theme of your Agenda Component.
Hide Event Details Show all events as Busy.
Show Date in Header Add date to the Agenda Header.
Start or end day when event start or end Display the Agenda start and end time by 24 hour clock or display Agenda start and end time using earliest and last event.
Color items by Color by calendar or events.
Disable pinch to zoom Adds an effect to expand or contract the calendar display.
Hide current time bar Display a line on the Agenda that illustrates the current time.
Allow users to change date Enable left and right arrows to allow users to change calendar display date.
Condensed View Display the agenda events in a single column.
Calendars to Include Select any available calendars to display. If no calendar is selected, the component must be provided at least one calendar ID via the calendar_ids property to display Nylas data.

Application Component Display Options

To enable most features, add them to your configuration. For example, allow_date_change by default is false. Adding it to your configuration will automatically make it true—no need to set it to true.

import React from "react";
import "./styles.css";
import "@nylas/components-agenda";

export default function App() {
return (
<div className="App">
<nylas-agenda
id="your-agenda-id"
access_token="your-access-token" // only if this component has been enabled for all accounts
calendar_ids ="your-calendar-ids" //only if using Nylas account data
allow_date_change
allowed_dates
auto_time_box
click_action
color_by="event"
condensed_view
eagerly_fetch_events
header_type
hide_current_time
hide_ticks
prevent_zoom
show_as_busy
show_no_events_message
theme="theme-1"
></nylas-agenda>
</div>
);
}
Name Type Description
allow_date_change boolean Allow your users to change the date using arrows. Allow date change will let them go through all calendar events instead of just one day. header_type must not be none. Default: false
allowed_dates Date[] | string Limits the dates that can be displayed by the Agenda to those provided by this property. Default: []
auto_time_box boolean Display the Agenda start and end time by 24 hour clock or display Agenda start and end time using earliest and last event. Default: false
calendar_ids string A comma-separated list of IDs of the calendars to display. You can get a list of calendar IDs by making a request to [GET /calendars][4]. At least one calendar ID must be provided if using Nylas data.
color_by enum Color the calendar by events or by calendar. If you have multiple calendars in one agent view, select calendar to show each calendar as it's own color. Available options: calendar, event Default: calendar
condensed_view boolean Display the agenda events in a single column. Default: false
eagerly_fetch_events boolean Pre-fetches nearby dates for smoother transitions. Default true
header_type string Changes the amount of information in displayed in the header. Available options: full, day, none Default full
hide_current_time boolean Display a line on the Agenda that illustrates the current time. Default:false
hide_ticks boolean Hide hours from the left margin. Default false
prevent_zoom boolean Adds an effect to expand or contract the calendar display. Default: false
show_as_busy boolean Show all events as Busy instead of event details. Default: false
show_no_events_message boolean Display a message if there are no events for the selected date. Default: false
theme enum Set the theme of your Agenda Component. Available options: theme-1, theme-2, theme-3, theme-4, theme-5. Default: theme-1

Custom Callbacks

You can't pass callbacks as attributes

You must select the element, for example document.getElementById, and then attach the custom properties.

Name Type Description
click_action(clickEvent, calendarEvent) function Triggered when a user clicks on an event. The callback is provided with the original click event as clickEvent and the event data as calendarEvent. If no callback is provided, the default behavior is to expand/collapse an event on click.

Emitted Events

The emitted event object will include a details property that contains the event payload.

Name Type Description
dateChange Date Requires allow_date_change to be true. Triggered when a user changes the date of the Agenda.

Allowed Domains

You can restrict the domains that your Component works on. Use glob patterns to enable or disable domains.

Some examples of glob patterns:

  • nylas.com will only match nylas.com
  • subdomain.nylas.com will match subdomain.nylas.com
  • *subdomain.nylas.com will match subdomain.nylas.com and sub.sub.subdomain.nylas.com
  • * will match any domain

Domain restriction only applies to the domain name. URL paths (/sub-path) or protocols (HTTPS) can not be restricted.

How Properties Are Handled

Nylas Components follow an order of operations to decide if the dashboard or code takes precedence.

  1. If the property is passed directly to the Component, use that first.
  2. If the property is not passed directly in the Component use the dashboard settings.
  3. If there are no properties set in the Component or the dashboard, use the Component defaults.

Extending Functionality

Here are a few ways to add more functionality to Nylas Agenda.

Multiple Calendars

You can display multiple calendars in a single application in a few ways.

To have multiple accounts in the same view, create an agenda component for each account.

In this example, there are 2 accounts with 1 calendar each (calendar_ids) displayed.

    <section>
<h2>Dorothy</h2>
<nylas-agenda
calendar_ids="ciw5iqmm8e8ywlhb8xl8fg8iz"
id="801d7467-8663-4800-bdf8-f86a366ff3d0"
/>
</section>
<section>
<h2>Kate</h2>
<nylas-agenda
calendar_ids="2stq9ckhdhnzvs4t8x2wlin9p"
id="801d7467-8663-4800-bdf8-f86a366ff3d0"
/>

To have 1 account with multiple calendars, add the calender_id of each account calendar you want to display.

      <nylas-agenda 
id="0e4d7f3-bf3b-4f0e-9faf-589ba9831d35"
calendar_ids="1234adv5tgh678h, 1234adv5tgh678h"
color_by="calendar"
></nylas-agenda>

Grab our CodeSanbox to start using multiple calendars with your Agenda.

Agenda Team Week View

The application uses demo data. Create a new Component when you're ready to use your data.

Change Calendar Grid

The default way to display the calendar is to show only one day at a time in a view. You can expand on this to show a full month in one view.

Agenda Team Month View

The application uses demo data. Create a new Component when you're ready to use your data.

Demo Apps

Fork any of our demo apps to get started

What's Next