xdg-portal

A wrapper around dbus to ease the use of XDG Desktop Portals.

The naming of methods (including parameters), properties and signals is the exact same as in dbus.
As of now (August 2026) all portals are supported.

Installation

xdg-portal is available on npm:

npm install --save xdg-portal

Examples

Check if a portal is available

import * as portal from "xdg-portal";

const client = await portal.client();
// Version is a property available on all portals.
// Reading it will never throw, but instead return 0 if the portal cannot be reached
const version = await client.desktop.GlobalShortcuts.version;
if(version > 0) {
    // do something with the portal
}
client.close();

Show a notification (send and forget)

import * as portal from "xdg-portal";

const client = await portal.client();
// await, so the notification is sent before the client is closed
await client.desktop.Notification.showNotification({
  title: "Hello World",
  body: "This is a notification from my app.",
  icon: "dialog-information"
});
client.close();

Ask the user to share their account information (request and wait for a response)

import * as portal from "xdg-portal";

const client = await portal.client();
const userInfo = await client.desktop.Account.getUserInfo("");
if(userInfo.response === 0) // According to the XDG docs: 0 = success, 1 = cancelled, 2 = other error
    console.log("User info:", userInfo.results);
else
    console.error("The user denied access to their account information.");
client.close();

Listen for low memory warnings (subscribe to a signal)

import * as portal from "xdg-portal";

const client = await portal.client();
client.desktop.MemoryMonitor.LowMemoryWarning.addListener((level) => {
    console.log("Low memory warning:", level);
});
await new Promise(resolve => setTimeout(resolve, 60000)); // listen for 1 minute
client.close();

Check if a camera is present (read a property)

import * as portal from "xdg-portal";

const client = await portal.client();
const haveCamera = await client.desktop.Camera.IsCameraPresent;
console.log("Is camera present:", haveCamera);
client.close();

Get the current location (use a session)

import * as portal from "xdg-portal";

const client = await portal.client();
const session = await client.desktop.Location.CreateSession();
client.desktop.Location.LocationUpdated.once((data) => {
    console.log("Location:", data);
});
await client.desktop.Location.Start(session, "");
await new Promise(resolve => setTimeout(resolve, 5000)); // wait for 5 seconds to receive a location update
await session.Close();
client.close();

Connect to a custom dbus bus

import * as portal from "xdg-portal";

const options: portal.DBusConnectionOptions = {
    busAddress: "unix:path=/tmp/my-custom-bus"
};

const client = await portal.client(options);
// Use the client as usual
client.close();