Upgrade Stripe's UI extension SDK
Upgrade your app to the latest version of @stripe/ui-extension-sdk.
This page provides a comprehensive guide to help you navigate the breaking changes introduced in each major version of the @stripe/ui-extension-sdk and outlines the necessary changes to upgrade your application.
We recommend upgrading the Stripe Apps CLI plugin by running stripe plugin upgrade apps
before updating the @stripe/ui-extension-sdk version. This ensures optimal compatibility, incorporation of the latest features, and security fixes.
@stripe/ui-extension-sdk v9 ![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
What’s new in v9![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Version 9 of @stripe/ui-extension-sdk
introduces property validation for all of its components. This version is more secure, mitigates bugs, and promotes adherence to coding best practices. After you install it, pay attention to TypeScript errors arising from invalid property values, as they could throw validation errors causing the application to crash.
Component changes![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
We made visual updates to several components. After you install the latest version, review your app to make sure that the components appear as they should.
Component | Breaking changes |
---|---|
Button |
|
DateField |
|
FormFieldGroup |
|
Link |
|
Tab |
|
TabPanel |
|
TextArea |
|
TextField |
|
Changelog![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
9.0.0![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Add runtime component prop validation to enforce type safe properties.
- Add
pending
prop toButton
component. - Add
new
variant value totype
prop inBadge
component. - Add more format options to
BarChart
andLineChart
components:- Add format style
decimal
. - Add
nice
option to have more pleasing axis limits. - Add
ticks
to specify the number of markets along an axis. - Add
tickFormat
to modify the display of the tick labels. - Add
zero
to control the visibility of the zero value. - Add
fractionalDigits
option to currency formats to control the precision of numeric values.
- Add format style
- The
onChange
prop in theDateField
component now directly receives the value instead of the change event. - The
layout
prop values in theFormFieldGroup
component have changed fromrow
andcolumn
tohorizontal
andvertical
. - Remove
tabKey
prop fromTab
andTabPanel
components. Use theid
prop instead. - Remove deprecated
className
prop fromButton
andLink
components. - Remove deprecated
invalid
prop fromFormFieldGroup
component. - Remove deprecated
onKeyPress
prop fromTextArea
andTextField
components. - Remove deprecated
background
property onBox
andInline
components’css
prop. Use thebackgroundColor
property instead. - Remove deprecated
layout
property onBox
andInline
components’css
prop. Use thestack
property instead. - Remove deprecated properties (
borderColor
,borderTopColor
,borderRightColor
,borderBottomColor
,borderLeftColor
) onBox
andInline
components’css
prop. Use thekeyline
property for border styling instead.
8.9.1![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Use fixed dependency versions.
- Fix test wrapper find methods.
8.9.0![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Add
value
prop toDateField
component. - Add deprecation notice to the
background
property onBox
andInline
components’css
prop. Use thebackgroundColor
property instead. - Add deprecation notice to the
className
prop onButton
andLink
components. - Add deprecation notice to the
invalid
prop onFormFieldGroup
component. - Add deprecation notice to the
layout
property onBox
andInline
components’css
prop. Use thestack
property instead. - Add deprecation notice to the
tabKey
prop onTab
andTabPanel
components. - Add deprecation notice to the border color properties (
borderColor
,borderTopColor
,borderRightColor
,borderBottomColor
,borderLeftColor
) onBox
andInline
components’css
prop. Use thekeyline
property for border styling instead. - Remove deprecation notice from
value
andchecked
props.
8.8.0![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Add
StripeFileUploader
component. - Add
platform
prop to environment context. - Add
appContext
to theExtensionContextValue
type. - Add types for
AuthorizedPermission
andAuthorizedContentSecurityPolicy
. - Add some utility functions for interacting with
appContext
:getUserAuthorizedPermissions
: Gets the intersection of the app’s authorized permissions and those of the current Dashboard user.isPermissionAuthorized
: Indicates if a permission is in the app’s authorized permissions.isSourceInAuthorizedCSP
: Indicates if a URL is in the app’s authorized connect or image sources.
8.7.0![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Add
roles
to the account passed to extensions in theuserContext
property.
8.6.0![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Add
secondaryAction
prop toSignInView
. - Add
target
toSignInView
action props. - Allow both
href
andonPress
onSignInView
action props.
8.5.0![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Add
constants
prop to environment context.
8.4.1![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Add
SignInView
component.
8.3.0![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Remove unsupported
contentUses
property fromTableCell
andTableHeaderCell
typing. - Updated
useToast
to returnshow
anddismiss
utility methods.
8.2.0![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
StripeAppsHttpResponse.
now returns a rejected promise if the HTTP response body was empty.prototype. toJSON() - Add support for calling
fetchStripeSignature
with nested JSON. - Fix
debug
to filter props according toall
option. - Add
tabKey
toTab
andTabPanel
. - Upgrade
stripe
package dependency to^9.
.11. 0 - Add
external
toLink
. - Add
setShown
prop toFocusView
. - Add
showToast
utility function for rendering toast notifications at the bottom of an app’s view.
8.1.0![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Fix
ExtensionContextValue
typing to markname
andobjectContext
values as possiblynull
. - Add
textAlign
toBox
css
. - Make
onSave
prop optional forSettingsView
components. - Upgrade to
@remote-ui/react
4.5.2. - Add
Sparkline
component.
8.0.0![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Add deprecation notice to the
value
prop onTextArea
,TextField
, andSelect
components. - Add deprecation notice to the
checked
prop onCheckbox
,Radio
, andSwitch
components. - Remove unsupported
outerRef
props from inputs.
7.1.0![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Add
brandIcon
andbrandColor
toContextView
.
7.0.0![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Deprecate
Notice
component; useBanner
instead. - Add
overflowX
andoverflowY
toBox
css
.
6.3.1![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Internal update, no user-facing changes.
6.3.0![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Add
Banner
component. - Add deprecation warning for
Notice
component. - Add
locale
toExtensionContextValue['oauthContext']
. - Add
overflowWrap
andwordBreak
toBox
css
properties. - Add
textTransform
toBox
andInline
css
properties. - Add
primaryAction
,secondaryAction
, andfooterContent
properties toContextView
. - Add
whiteSpace
toBox
css
properties.
6.2.0![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
BarChart
andLineChart
improvements:- Configurable axis formatting.
- Configurable value formatting.
- Configurable channel domains.
- Configurable channel ranges.
- Show/hide axis labels and ticks in charts.
- Show/hide grid lines in charts.
- Show/hide tooltips in chart presets.
- Show/hide legends in chart presets.
6.1.0![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Add a confirmation dialog to
FocusView
. - Add
Chip
andChipList
components. - Update the
getDashboardUserEmail
utility to return the email directly and reject the promise if there’s an error. - Fix React components not being accepted in the
label
prop of form elements. - Expose
text-overflow: ellipsis
andword-wrap: normal | break-word
onBox
css
. - Add
country
to the account passed to extensions in theuserContext
property. - Add
data:
URL support for theImg
component. Learn more about theImg
component.
6.0.0![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Deprecate email in view context.
- Consolidated utilities in
/utils
path. - Fixed react-reconciler dependency issue affecting unit tests.
5.0.1![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Fix prop types for
Switch
,Checkbox
andRadio
.
5.0.0![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Adds the
Accordion
,Icon
,Spinner
, andTooltip
components. - Adds tooltips to
BarChart
andLineChart
. - Fix prop typing for
BarChart
andLineChart
. - Deprecates legacy view context parameters.
- Enables setting width through
css={{ width: .
on. }} Select
,TextArea
,TextField
,Button
, andLink
. - Enables setting internal horizontal alignment through
css={{ alignX: .
on. }} Button
andLink
. - Adds the
clipboardWriteText
function. - Adds the
getDashboardUserEmail
function.
4.0.0![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Deprecates the
slot
property.
3.2.0![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Adds the
createOAuthState
function. - Adds
oauthContext
to theExtensionContextValue
type.
3.1.0![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Adds the
Img
component.
3.0.0![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Adds support for the
Notice
,Charts
, andTabs
components. - Breaking changes:
ListItem
: Previously, content passed as children would be the primary content rendered in the component. Now, main content is passed to thetitle
prop. Thedescription
slot has also been reassigned to asecondaryTitle
prop.MenuTrigger
: This component has been deprecated in favor of atrigger
prop on theMenu
component. Slot API usage has also been removed.
- Removed permissions from being passed into the user context.
2.2.1![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Expose
docs.
files injson dist
.
2.2.0![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Add
actions
prop toContextView
.
2.1.0![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Introduces
ButtonGroup
component. - Removes
margin-bottom
from form controls. - Gives Button
white-space: nowrap
andalignY: center
by default. - Button themes now set a
min-height
on all size variants. - Makes
Link
andButton
shrink to fit their content. - Exposes
defaultValue
attribute onTextField
andTextArea
. - Allows
error
anddescription
to be hidden on form controls through thehiddenElements
prop. - Exposes
invalid
andsize
props onSelect
andTextArea
. - Exposes
defaultChecked
attribute onRadio
. - Exposes
resizeable
androws
props onTextArea
. - Fixes invalid state on control components.
- Fixes
Chip
onDropdown
firing twice. - Fixes
Divider
rendering.
2.0.3![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Returns a promise from
useRefreshDashboardData
that resolves after dashboard data is refreshed. - Adds
fetchStripeSignature
method that optionally accepts additional request payload. Signature can be used to make authenticated request to your app’s backend. - Fixes an issue where the test element check method
.
would sometimes fail to identify a component.is
2.0.2![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Fixes an issue with the
testing
package in which comopnents with fragment props were not findable usingwrapper.
.find()
2.0.1![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
2.0.0![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Fixes a render error with
SettingsView
. - Updates
SettingsView
types to match the available component props. - Adds a
getMockContextProps
helper for testing. Learn more about context props. - List component now accepts
React.
as a valid type to theReactNode value
prop, rather than just astring
. - Adds hover state to ListItem components.
- Updates ListItem component such that hover state is only visible when there is an action associated.
- Fix Select rendering when multiple is true.
- Fix Checkbox onChange firing twice.
1.1.7![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Adds a “testing” module, which includes helpers for writing Jest tests for apps. Learn more about UI testing.
- Fixes some components that take React nodes as props:
MenuGroup
now supports thetitle
prop.FocusView
now supports thefooterContent
prop.SettingsView
now supports theheaderActions
prop.
- Some type fixes and grammar updates.
1.1.6![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- Added types for
FocusView
,SettingsView
, andContextView
. - Exporting a new constant
STRIPE_
from http_client to be used when initializing the Stripe API client.API_ KEY