Widgets

Descope Widgets are embeddable components designed to facilitate the delegation of operations to your application's users. Through the console, you can fully customize the display and functionality of your widgets according to your user's needs.

These widgets can be utilized in both B2B and B2C contexts, allowing your users and admins to perform various role, user, and project level management from within your application.

Widgets

Creating A Widget

You can create a widget from the widgets page of your Descope console, starting from one of our widget templates or by importing one from a JSON file.

From the widget template library, you can filter widgets based on whether they are for end users or admins and based on use case. You can also preview what the template looks like from the library before creating the widget.

After you create a widget, you can edit its design and logic. You can add/remove/alter buttons and text within the widget, as well as modify the design of the widget container and the components within. Within the User Profile widget, you can include custom attributes, and mark fields as Read-only and/or Mandatory.

To edit a specific part of the widget, simply click on it and utilize the Design & Behaviors toolbar on the right:

Inside preview mode you can see how the widget will look like on the client side, including actions and light/dark mode:

Read more about User Widgets, Admin Widgets, the hosted Admin Portal, and how to customize Widget Flows.

Restricting Access to Widgets

By default, any user with the User Admin permission for a tenant can see and use every Admin Widget hosted in your app or in the Admin Portal, such as user management, role management, and access key management. User Widgets like the User Profile and Applications Portal widgets don't require the User Admin permission: any authenticated member of the tenant sees them by default. For finer control, such as letting one admin see the User Management widget but not the Audit widget, or hiding the Applications Portal widget from some users, configure required permissions on a per-widget basis. This applies to both User Widgets and Admin Widgets.

Configuring Required Permissions

1. Go to the Widgets page in the Descope Console and open the settings for the widget you want to restrict.
2. In the widget settings dialog, find the Required permissions field and select one or more of your project's existing permissions.
3. Save the widget.

Leaving this field empty keeps the widget's default behavior: Admin Widgets are available to anyone with the User Admin permission and User Widgets are available to any authenticated member of the tenant.

How Enforcement Works

• A user must hold all of the permissions selected for a widget to see it and perform its actions. For Admin Widgets, the User Admin permission is also required. Missing even one required permission hides the widget.
• Enforcement applies both when the widget is embedded directly in your app and when it's hosted in the Admin Portal, where the widget is simply omitted from the left navigation for users who don't qualify.
• If a permission referenced by a widget is later deleted from the project, it's automatically removed from that widget's required permissions list.

Flows within Widgets

Descope Widgets are powered by Flows running underneath each component, giving you full control over the logic and user experience for every widget action. This includes customizing widget behavior, configuring component flows, running batch actions on multiple users, passing flow inputs into widgets, and more.

See Widget Flows for details.

Customizing a Widget

You can customize the Widget Component by passing in the following props. These customizations can be applied to any of the available widgets:

• theme: theme can be "light", "dark" or "os", which auto selects a theme based on the OS theme. Default is "light"
• styleId: style Id can be the id of the style you wish to run your widget with
• form: key/value pairs forwarded into widget flows as flow inputs. Any {{form.*}} references configured in a widget flow will resolve to these values.
• client: key/value pairs forwarded into widget flows as client metadata. Any {{client.*}} references configured in a widget flow will resolve to these values.
• debug: debug can be set to true to enable debug mode
• locale: locale can be any supported locale that the widget is translated to. If not provided, the locale comes from the browser.

For example, this is how you would customize the User Management Widget:

import { UserManagement } from '@descope/react-sdk';
...
  <UserManagement
    widgetId="user-management-widget"
    tenant="tenant-id"
    theme="dark"
    styleId="my-style-id"
    debug="true"
    locale="en"
  />

Disabling and Activating Widgets

When you are not actively using a widget, you can disable it from the Descope Console. This can be done by selecting the widget(s) using the checkboxes on the left, then clicking the Disable button at the top of the table, or by clicking the three dots on the right and selecting Disable from the dropdown menu. To re-enable the widget(s), follow the same steps but select Activate instead.

Exporting a Widget

Widgets can be exported from the Descope Console as a JSON file.

This file will include the the design of the widget along with the actions of each button included in the widget. Each button's action is designed as a flow that runs using information from the widget. All of these flows being used by the widget are also exported in the file.

The widget's JSON data can be imported to another Descope project's widgets to copy a custom widget.

Show Code

Within the Widgets page of the Descope Console, you can generate a frontend code snippet by clicking the three dots at the right of the widget and selecting the Show Code option.

You can select between various frontend frameworks to integrate the selected widget into your app.

SDKs

You can use the below SDKs to implement widgets in your app.