WorkOS Widgets

WorkOS Widgets are React components that provide complete functionality for common enterprise app workflows, for example a Users Management Widget that provides a UI for inviting, removing and editing users.

This guide will cover how to add a widget to your app, configure CORS, and supply an authorization token for the widget.

First, install the @workos-inc/widgets package from the npm registry, along with its peer dependencies:

npm install @workos-inc/widgets @radix-ui/themes @tanstack/react-query

Because WorkOS widgets issue client-side requests to WorkOS, it is necessary to configure your site as an allowed web origin. Adding this in the Authentication section of the dashboard will prevent CORS issues when using the widget.

Widgets must be supplied with an authorization token. The token can be acquired in one of two ways:

const authToken = await workos.widgets.getToken({
  userId: user.id,
  organizationId,
  // scopes corresponds to the permissions required for each widget (see below)
  scopes: ['widgets:users-table:manage'],
});

To successfully generate a token, the user must be assigned a role with the correct permissions for the widget.

WorkOS Widgets are powered by Radix Themes, which are styled out-of-the box when you import its CSS in your app.

import '@radix-ui/themes/styles.css';

You can customize Widgets by passing a theme prop to WorkOSWidgets. This prop accepts an object with the same options as Radix themes.

function UsersTable({ authToken }) {
  return (
    <WorkOsWidgets
      theme={{
        appearance: 'dark',
        accentColor: 'green',
        radius: 'medium',
        fontFamily: 'Inter',
      }}
    >
      <UsersManagement authToken={authToken} />
    </WorkOsWidgets>
  );
}

The <UsersManagement /> widget allows an organization admin to manage the members in an org. Admins can invite new users, remove users, and change roles all within the widget.

In order to use the User Management widget, a user must have a role that has the widgets:users-table:manage permission.

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

// authToken is 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 UserTable({ token }) {
  return (
    <WorkOsWidgets>
      <UsersManagement authToken={token} />
    </WorkOsWidgets>
  );
}

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

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

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