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>
  );
}

If you choose not to use the theming capabilities in Radix Themes, you can style Widgets using CSS. We recommend starting with the layout.css stylesheet from Radix Themes, as well as the base.css stylesheet from WorkOS Widgets. These styles provide a base level of functional styling without opinionated design choices.

import '@radix-ui/themes/layout.css';
import '@workos-inc/widgets/base.css';

Individual elements in Radix themes are accessible via CSS class selectors prefixed with woswidgets-. For example, you can add your own button styles by selecting the woswidgets-button class.

.woswidgets-button {
  border-radius: 4px;
  color: hsl(0 0% 100%);
  background-color: hsl(272deg 81% 56%);
  background-image: linear-gradient(
    to top right,
    hsl(272deg 81% 56%),
    hsl(271deg 91% 65%)
  );
  /* ... */
}

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>
  );
}