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, and the hosted Admin Portal.

Flows within Widgets

Descope Widgets are powered by Flows running underneath each component. This means you have full control over the logic and user experience for every widget action.

Customizing Widget Behavior

Each widget component has associated flows that handle the underlying operations. You can modify these flows to customize the logic for actions like:

• Email Updates: Control the verification process when users update their email, including how verification codes are sent and validated
• Passkey Management: Customize the logic for adding or removing passkeys, including any additional security checks
• Password Changes: Add custom validation rules, strength requirements, or notification logic when users reset their passwords
• Profile Updates: Add custom validation or approval workflows for profile changes
• User Creation/Management: Customize approval processes, notification logic, or validation rules for admin widgets

Configuring Component Flows

Every widget consists of components that have associated flows you can modify. There are several ways to configure and customize these flows:

1. Component Flows: Each widget component has flows that handle its operations. You can modify these flows directly to customize the behavior, such as changing how email verification works or how profile updates are processed.

2. Custom Button Actions: Some widgets (like the User Management Widget) allow you to add custom buttons. Newly added buttons include an empty flow that you can access under the Behavior tab in order to fully customize any logic you need for a button. For bulk operations on multiple selected users, see Batch User Actions below.

3. Behavior Settings: You can enable additional built-in capabilities from the Behavior tab in the widget settings. For example, in the User Profile Widget, you can enable the ability to remove passkeys, which activates a flow that you can then modify to customize the removal process.

To edit a flow, click on the component or button you want to customize, navigate to the Behavior tab in the settings panel on the right, and click Edit next to the relevant flow to open the flow editor.

Batch User Actions

In the User Management Widget, administrators can select multiple users from the table and run a custom button flow to perform bulk operations on all selected users using User / Batch Actions.

Build the Flow

When the custom button is clicked, the widget launches its associated flow with context about the selected users. To process them in bulk:

1. Open the button's flow from the widget editor (Behavior tab → Flows → Edit).
2. Add any screens or inputs needed to collect additional information from the administrator.
3. Add a User / Batch Action to the flow.
4. Configure the action, such as deleting users, updating their status, assigning roles, or adding applications.
5. Optionally add a confirmation screen, audit event, connector action, or webhook at the end.

Using Role or Application Selectors

Some batch actions require the administrator to choose roles or applications before the batch action can run.

For actions involving roles, such as Set Roles, Add Roles, or Remove Roles, add a screen to the flow with a Roles Selector input component. The values which will appear in the dropdown can be populated under the Behavior tab → Values. The selected roles will then be passed into the relevant User / Batch role action.

Similarly, for actions involving applications, such as Add Applications or Delete Applications, add a screen to the flow with an Applications Selector input component. The values which will appear in the dropdown can be populated under the Behavior tab → Values. The selected applications will then be passed into the relevant User / Batch application action.

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
• debug: debug can be set to true to enable debug mode

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"
  />

<user-management tenant="tenant-id" widgetId="user-management-widget" theme="dark" styleId="my-style-id" debug="true"/>

<template>
	<UserManagement tenant="tenant-id" widget-id="user-management-widget" theme="dark" style-id="my-style-id" debug="true"/>
</template>

<script setup>
import { UserManagement } from '@descope/vue-sdk';
</script>

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

<!DOCTYPE html>
<html>
  <head>
  </head>
  <body>
    <script src="https://static.descope.com/npm/@descope/user-management-widget@x.x.x/dist/index.js"></script>

    <descope-user-management-widget
      tenant="tenant-id"
      project-id="project-id"
      widget-id="user-management-widget"
      theme="dark"
      style-id="my-style-id"
      debug="true"
    ></descope-user-management-widget>
  </body>
</html>

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.