Build Customizable User Interactions With Nylas Components

Nylas Components are customizable JavaScript UI/UX elements that make it easy to implement a complete scheduling and communications experience.

Phil Renaud | April 9, 2021

If you haven’t yet heard, Nylas has a new set of components to help developers build email, calendar, and contacts integrations much more quickly and easily. Interfaces for these sorts of applications have been commonly used for a long time, and most people have come to expect certain norms from them. For example, if you see a snippet of an email and click on it, you might expect to see that email expand to a full text view. Similarly, you might also expect that swiping left on your weekly calendar will take you to the next week’s events. These examples are fairly obvious, but not every action is so unambiguous. 


Consider the Contact List: it shows a list of your contacts, their email address, and the last time the two of you communicated via email. What happens when you click a contact? Should it open your email client? What if you wanted to do something more complex with your contact list, like add multiple users to a group chat? 

Want a PDF of this article?

Share it with a friend or save it for later reading.

A similar predicament exists for the Agenda Component: what happens when you click on an event? Should it change your attendance status, expand the event details, email the participants, or something else?

At Nylas, we’ve been thinking about problems like this as we build our Components library. How do you build a component that’s supposed to cover a common, ubiquitous pattern like a list of your contacts, and still give developers room to modify it to their needs? We are always mindful of the developer experience for our products, and that means helping developers get up and running quickly while also giving them complete freedom once they get the hang of things.


We’ve identified three guiding principles that we believe will help us achieve these goals.

  1. Define the obvious, make it painless
  2. Enable custom logic everywhere
  3. Subscribe to any user interaction

This post will explain how these principles have been used while building the Nylas Components.

Define the Obvious, Make it Painless

This is where it all starts for us, we think about which interactions would cover the majority of expected use cases and we come up with an obvious solution that has a clear name. For example, the Contact List View accepts click_action=”select” to let users toggle the selected status of a contact to trigger unique display options for that specific individual. Alternatively, you can pass click_action=”email” and instead launch the Email Compose View to let the user draft an email to the selected contact.


This works great for most developers, but what if you want a more complex or nuanced action to take place? Or further, what good does it do for us to have selected a contact? This is where we start adding interaction by way of our second guiding principle.

Enable Custom Logic Everywhere

Since there’s no way we can guess all the ways our developers will want to interact with these components, we make it possible to pass more than specific strings like ‘select’ or ‘email’ as the action property; the Nylas Components also allow you to pass a custom function. The next example shows you how to pass a custom function to Agenda View that lets a user email all participants of an event using their default email client by clicking that event in their agenda.

<script>
  function onEventClicked(_, event) {
      if(event.participants.length=== 0) {
        return;
      }
      const contacts = event.participants
        .map((participant) => participant.email)
        .join(";");
      window.location.href = `mailto:${contacts}`;
    }
</script>

<nylas-agenda
        click_action={onEventClicked}
        id="MY_COMPONENT_ID" 
/>  

This approach lets you seamlessly integrate our components into the existing architecture of your app and only tie in Nylas Components where you see fit. When connected to an end-user’s account, these components let you instantly integrate predictable JSON data representations of all email, calendar, and contacts functionality.


The use of custom logic is only half of the approach we’ve taken with Components to better customize user interactions. This brings us to our third guiding principle.

Subscribe to Any User Interaction

A common approach to application design is Data Down, Actions Up; that is, you shouldn’t pass higher-order functions into child components, but you should have child components emit signals to trigger higher order functions. This is the first design pattern we decided to implement for the Nylas Components because we think it’s a great way to enable customized user interactivity.

We chose Svelte as the framework for the Nylas Components which includes a data-passing flow called a Dispatch. This allows the components to handle interactions as expected for their primary use case while also exposing interactions with child elements in the component for your app to do with as it needs. For example, clicking a Contact in the <contacts-list> exposes a contactClicked event, which your app can watch via .addEventListener(“contactClicked”, (event) => {…}). This lets you utilize both the clicked contact and the rest of the list.


Here’s an example of how the Contact List Component uses Svelte’s clean interface to dispatch events:

dispatchEvent("contactClicked", {
        event,
        contact,
        contacts: hydratedContacts,
      });

These events are super easy to receive one layer higher in your app:

window.addEventListener("DOMContentLoaded", ()=> {
    document
        .getElementsByTagName("nylas-contact-list")[0]
        .addEventListener("contactClicked", (event) => {
          contactsClicked = event.detail.contacts.filter((c) => c.selected)
              .length;
    });
});

Maximize Customization, Minimize Headaches

We believe that the combination of of these three approaches maximizes the interaction customization options for front-end engineers while keeping the the base version of the components simple and approachable. In other words, we’ve prioritized making it easy to get off to a running start while being proactive about practical nuances that pop up when building an email, calendar, and contacts integration. We know that these components need to be straightforward to use, and you can integrate Nylas Components into your app with as little as 5 lines of code. 


Sign up for a Nylas account to give them a try. We’d love to know what you think!

Phil Renaud

Phil Renaud is Director of Engineering at Nylas in Toronto. He spends his time thinking about javascript, natural language processing, and data visualization.