Pipes Widget

A widget for displaying and managing connected accounts with Pipes.

The <Pipes /> widget allows users to manage their connections to third-party providers. Users can view the available providers, connect their accounts, reauthorize when needed, and disconnect their accounts.

Read more in the Pipes guide.

JavaScript

 import { Pipes, WorkOsWidgets } from '@workos-inc/widgets';

/**
 * @param {string} authToken - A widget token that was fetched in your backend. See the
 * "Tokens" section of this guide for details on how to generate the token
 */
export function PipesPage({ authToken }) {
  return (
    <WorkOsWidgets>
      <Pipes authToken={authToken} />
    </WorkOsWidgets>
  );
}

 import { useAuth } from '@workos-inc/authkit-react';
import { Pipes, WorkOsWidgets } from '@workos-inc/widgets';

export function PipesPage() {
  const { isLoading, user, getAccessToken } = useAuth();
  if (isLoading) {
    return '...';
  }
  if (!user) {
    return 'Logged in user is required';
  }

  return (
    <WorkOsWidgets>
      <Pipes authToken={getAccessToken} />
    </WorkOsWidgets>
  );
}

Filtering integrations

By default the widget renders every integration the organization has enabled. The filter prop narrows which of those are displayed, so a page can mount several <Pipes /> instances, each scoped to a subset – for example, one instance per integration, under its own heading and description.

Filtering is display-only. Every instance still fetches the same full set of enabled integrations in a single shared request, and filter only controls which rows are rendered. A filter that matches nothing renders an empty widget.

Filter criteria

Pass an object with any of slugs, integrationTypes, or authMethods. Provided criteria are combined with AND, and an omitted criterion is ignored. An integration that doesn’t declare authMethods is treated as oauth.

Because the object is serializable, this is the form to use when the widget is rendered from a React Server Component.

Filter criteria

JavaScript

 import { Pipes, WorkOsWidgets } from '@workos-inc/widgets';

/**
 * @param {string} authToken - A widget token that was fetched in your backend. See the
 * "Tokens" section of this guide for details on how to generate the token
 */
export function PipesPage({ authToken }) {
  return (
    <WorkOsWidgets>
      <h2>Google Drive</h2>
      <Pipes authToken={authToken} filter={{ slugs: ['google-drive'] }} />

      <h2>Bring your own API key</h2>
      <Pipes authToken={authToken} filter={{ authMethods: ['api_key'] }} />
    </WorkOsWidgets>
  );
}

Filter predicate

To filter on any other field – such as whether the user is currently connected – pass a function that receives a DataIntegration and returns whether to render it.

Functions can’t be serialized across the server/client boundary, so a predicate has to be defined in client code. If the surrounding page is a Server Component, wrap the widget in your own "use client" component that owns the predicate and receives only serializable props, such as the auth token.

Filter predicate

JavaScript

 'use client';

import { Pipes } from '@workos-inc/widgets';

/**
 * A predicate can't cross the server/client boundary, so it has to be defined in
 * client code. This component owns the predicate and receives only the
 * serializable token from the server component that renders it.
 *
 * @param {string} authToken - A widget token that was fetched in your backend. See the
 * "Tokens" section of this guide for details on how to generate the token
 */
export function ConnectedPipes({ authToken }) {
  return (
    <Pipes
      authToken={authToken}
      filter={(integration) => integration.installation != null}
    />
  );
}

API Reference

Prop	Type	Default	Required
`authToken`	`AuthToken`	No default value	Required
`filter`	`PipesFilter`	No default value	Not required