UI Extension SDK API reference

An index of all fields, types and descriptions for the UI Extension SDK API.

UI extensions have access to context props and utility functions that let them interact with an app’s users and the Stripe Dashboard ecosystem. This page documents these values and functions.

Props

Views are passed props that the extension can use for context on where the extension is being displayed. Your view can take some or all of these props as arguments, and they’re of type ExtensionContextValue.

User context

The userContext prop has data about the end user using your app, including these fields:

RoleDefinition

A role definition has these fields:

Environment

The environment prop has data about the page a user is viewing, including these fields:

OAuth context

The oauthContext prop contains information about the current OAuth workflow, if one is underway.

App context

The appContext prop contains information about the user’s app install, and has the following fields:

Utility functions

The UI extension SDK provides these functions to help apps interact with the Stripe API, the Dashboard user and Dashboard navigation.

• clipboardWriteText —Write text to the end user’s clipboard.
• createHttpClient -Get an authenticated Stripe API client.
• createOAuthState —Obtain values to use when you create an authorization link in an OAuth workflow.
• fetchStripeSignature —Get a signature from Stripe’s servers.
• getDashboardUserEmail —Get the end user’s email address.
• getUserAuthorizedPermissions – Get the intersection of the app’s authorised permissions and those of the current Dashboard user.
• isPermissionAuthorized – Indicate whether a permission is currently in an app’s authorised permissions.
• isSourceInAuthorizedCSP – Indicate whether a URL is currently in an app’s authorised content security policy.
• navigateToDashboardRoute – Programmatically navigate to a different Dashboard route.
• showToast —Show a toast message to the user.
• useRefreshDashboardData – Enable your view to update data in the Dashboard.
• useStorage —Share data across different viewports of a Stripe App.

clipboardWriteText

Write text to the app user’s clipboard. The user can then paste it as if they had copied it.

To use this function, first import it from the SDK:

For example, provide a button that copies Hello, world! to the clipboard when pressed. In a real app, you could use this to copy an address, invoice number, or other important detail.

createHttpClient

Obtain an authenticated Stripe API client for the installed user’s account. You must use the the related setting provided by the SDK to give your client the permissions defined in the app manifest.

To use this function, first import it from the SDK and then provide its values to the Stripe constructor from stripe-node.

For an example in context, see Build a UI.

createOAuthState

Obtain state and challenge values to use when you create an authorisation link in an OAuth workflow.

To use this function, first import it from the SDK.

For an example in context, see Add authorisation workflows.

fetchStripeSignature

Get a signature from Stripe’s servers. Your UI extension can use this signature to send signed requests to your app’s backend.

To use this function, first import it from the SDK.

Caution

In preview mode, the fetchStripeSignature function errors until you complete your first app upload. See server-side logic for setup steps.

For more details and an example in context, see server-side logic docs.

getDashboardUserEmail

Get the app user’s email address.

To use this function, first import it from the SDK.

You must also include the user_email_read permission in your app manifest. Add it using a CLI command or edit the app manifest file directly.

Command Line

Select a language

CLI command

App manifest

No results

stripe apps grant permission user_email_read "EXPLANATION"

For example, access the app user’s email in a view by getting it using the getDashboardUserEmail function and storing it in a React state variable.

getUserAuthorizedPermissions

Gets the intersection of the app’s authorised permissions and those of the current Dashboard user.

For instance, if the app’s current authorised permissions are event_read and charge_write, but the current Dashboard user has a view_only role (that is, no edit permissions), calling the function returns the array ['event_read'].

To use this function, first import it from the SDK.

isPermissionAuthorized

Indicate if a permission is in the app’s authorised permissions. Throws an error if the permission isn’t on the app manifest.

To use this function, first import it from the SDK.

Gating functionality by permission

This function can gate app functionality by user authorised permissions.

For instance, on the customer details page, only update customer details if the app user has authorised the customer_write permission.

isSourceInAuthorizedCSP

Indicate if a URL is in the app’s authorised connect sources or image sources.

To use this function, first import it from the SDK.

navigateToDashboardRoute

Programmatically navigate from a Stripe App to a different Dashboard route. This is useful for navigating the user to a related Dashboard page in response to an in-app action.

Note

navigateToDashboardRoute is only available in SDK version 9.2.0 and later.

To use this function, first import it from the SDK:

For example, navigate to a specific customer’s details page when a button is pressed:

You can also navigate to your app’s own full-page view by using the fullPage route descriptor:

showToast

Render a toast at the bottom of your view to inform the user about the status of an action. For example, a toast can show a user whether an API call succeeded or failed.

The showToast() function takes two arguments, a message and options. The function is defined as follows:

type ToastType = "success" | "caution" | "pending" | undefined;
type ToastOptions = { type?: ToastType; action?: string; onAction: () => void; }
const showToast: (message: string, options?: ToastOptions) => Promise<{
 update: (updateMessage: string, updateOptions?: ToastOptions) => void;
 dismiss: () => void;
}>;

Toast messages can’t exceed 30 characters in length or be empty. If a message is too long or empty, the console logs an error.

Unless they’re of type pending, toasts dismiss automatically.

Toasts can also prompt the user to take an action. Clicking the action button automatically dismisses the toast.

useRefreshDashboardData

Enable your view to update data in the Dashboard. This function returns another callback function. Store that callback, and call it when Stripe data changes. When you call it, the Dashboard updates to reflect the new values.

To use this function, first import it from the SDK.

For instance, on a customer details page, get the callback function that refreshes Dashboard data, and then call it after updating the current customer.

useStorage

Note

The useStorage React hook is only available in SDK version 9.x.

You can use the useStorage React hook for reading and writing shared data across different viewports of a Stripe App.

This hook synchronises state between all active instances (viewports) of your Stripe App within the same browser. When the value updates in one instance, all other instances in the same browser reflect the change automatically. This is session-based storage that exists only while the app runs.

This hook can help you:

• Coordinate state between multiple viewports of your app.
• Avoid redundant API calls by caching fetched data and sharing it across viewports.

The hook has the following limitations:

• Values are limited to strings, so use JSON. stringify or JSON. parse for complex objects.
• Storage isn’t persistent between app sessions.
• Storage changes don’t synchronise between different browsers or devices.

The following example shows how two independently rendered instances of the same app can synchronise the value of a variable across different viewports. Try opening this app in multiple tabs to see how cross-window synchronisation works.

Loading example...

Loading example...

See also

• How UI extensions work
• Viewports reference
• Using Roles in UI Extensions