, 2021

Introducing Portal Windows for Electron

by Cyrus Roshan, Engineer @Tandem | GitHub Repo

What’s the piece of technology that reduced your headache the most in the last year?

For me, it’d be Portal Windows. It's a library we made at Tandem that lets you render and position native windows as simply as you render and position tooltips in your React app.

tired: juggling your free time. wired: juggling some portal windows

A year ago, making changes to other windows was a slog.

To trace the flow of data through our app, you would have to jump from file to file. Stores in the renderer sent messages to the node process, which then forwarded them to the renderer process for the window that was displayed. If you wanted to add a small icon to a row on our tooltips, users would have to download a new desktop app to see it.

And worst of all, these changes took so long to make.

Today, every single one of those problems is gone, and I enjoy window-related tickets. I don't have to write a single line of desktop code, or do any message-passing. I mostly just write React components, as if there were no windows involved.

Not only that, but behavior we didn’t consider a year ago, because it was prohibitively difficult, is now simple.

  • Rendering a window onto multiple screens, even as screens are added/removed,
  • doing complicated bounds correction,
  • positioning a window relative to an element on another window, even as the parent window moves and gets resized?

All covered. You too can feel great while writing complex window-management code.

Now, here’s a high-level of how Portal Windows work, a few simple examples, a few examples of how we use them today in the Tandem app, and then the source code.


Portal Windows are made up of a three-layer system:

  • Integration with React, allowing you to treat a window as a component in your tree, change its props, render elements inside it (thanks to React Portals)
  • A window management store, which keeps track of window and screen state, allowing relative positioning of windows, bounds correction, and multi-screen rendering support
  • Desktop-side code that enables the frontend to apply and receive updates, and create and address windows

What does this let you do? Great things!


If you enjoy using Tandem, you might be familiar with these windows, and their use cases:

Meeting reminders: get reminded of your meeting before it starts, and have Tandem automatically launch it for you at the start time. Shown on every screen.
Chatbox: when untoggled, new messages pop up to the left of the callbox, and slowly fade. When toggled, it remains open and shows chat history.

Screenshare: fetches windows + screens, and lets you share them. Once you screenshare, 'end screenshare' window appears on the bottom of the screen you're sharing to let you end it quickly.

Being able to use portal windows means that the "End Screenshare" window ended up being only ~100 lines of code total, and took <1hr to build.

Using Portal Windows

Remember the swarm of windows in the video at the top? Here's the code behind it, and here's a simpler version that only has one portal window.

You can follow the steps to get it integrated in your existing Electron app here, or copy a fresh project to play around with.

This tech has cut down on the time it takes to ship new features drastically, and we’re open-sourcing it as a gift to the community. Check out the source code here! (licensed MIT)

Does this interest you? Let us know—we’re hiring! Email us at