Quick Start

A step-by-step guide for setting up WorkOS Widgets in your application.

Installation

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

Install packages

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

WorkOS Widgets uses Radix Themes for its UI components and style customization APIs, while TanStack Query is used for data fetching and caching. Since both libraries are often used in applications, we require them as peer dependencies to avoid duplication, version conflicts, and bloated bundles.

Widgets can be used in any client- or server-rendered React application. See our Widgets examples on GitHub to see how they can be integrated in various frameworks.

Styles

WorkOS Widgets are powered by Radix Themes, which provides beautiful default styles with zero configuration. Start by importing styles exported from both Radix Themes and WorkOS Widgets.

CSS imports

CSS

 /* Provides styles for Radix Themes components and its theming API */
@import '@radix-ui/themes/styles.css';
/* Provides additional styles specific to WorkOS Widgets */
@import '@workos-inc/widgets/styles.css';

Widgets can be customized using the theme prop or with plain CSS. See the styling guide for more details.

Root component

The WorkOsWidgets component should be rendered at the top of your application. This component is responsible for managing context for data fetching and providing theme styles to all Widgets.

Root component

JavaScript

 function App({ children }) {
  return <WorkOsWidgets>{children}</WorkOsWidgets>;
}

CORS configuration

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.

Authorization TokensEnsure Widgets have the appropriate permissions in your application

Up next