Redesigned Components in Core 2
The new version ships with improved design and UX across all of Clerk's UI components. If you have used the appearance
prop or tokens for a custom theme, you will likely need to make some adjustments to ensure your styling is still looking great. If you're using the localization prop you will likely need to make adjustments to account for added or removed localization keys.
The sections below contain more info on each change made to the customization ids and localization keys for reference. Regardless of how thoroughly you have reviewed the following information, we still recommend that you ensure that you have taken some time to manually look through each of your views to ensure that everything looks good still.
Appearance Changes
Within <UserProfile />
, Multi-Factor Auth is Added via Dropdown
<UserProfile />
, Multi-Factor Auth is Added via DropdownWithin the <UserProfile />
component (which is also rendered by <UserButton />
), adding a multi-factor auth (MFA) method is now rendered as a dropdown instead of a modal. If you were relying on the modal for any sort of customizations, these customizations will need to be adjusted to the new form factor.
Two new appearance prop keys were added to aid with this process: cl-menuList__mfa
for styling the list of MFA factors, and cl-menuItem__mfa
for styling individual items.
Breaking Changes to appearance variables
Several appearance variables have been removed or renamed. If you were using these variables in your application, you will need to update your code to use the new variables.
- The
fontSmoothing
variable has been removed. - The
shadowShimmer
variable has been removed. - The
colorAlphaShade
variable has been renamed tocolorNeutral
.
Settings
-> General
tab in OrganizationProfile
Settings
-> General
tab in OrganizationProfile
The "Settings" tab within the <OrganizationProfile />
component has been renamed to "General". If you are linking directly to /organization-settings
from anywhere, the link will need to be updated to /organization-general
.
If you are customizing the component by re-ordering the pages, the label used to target this page must be changed from settings
to general
as well.
If you are using the appearance prop to customize the appearance of the <OrganizationProfile />
component, please note that the cl-profilePage__organizationSettings
key has also been changed to cl-profilePage__organizationGeneral
to be consistent with the naming change.
Within <UserProfile />
, Account and Security Pages Separated
<UserProfile />
, Account and Security Pages SeparatedWithin the <UserProfile />
component (which is also rendered by <UserButton />
), the "Account" and "Security" pages now live within their own tabs. Previously, "Security" was a section within the "Account" tab. The "Security" page can now be directly linked to under the /security
path if desired.
Within <UserProfile />
, Connected Accounts Added via Dropdown
<UserProfile />
, Connected Accounts Added via DropdownWithin the <UserProfile />
component (which is also rendered by <UserButton />
), adding a connected account is now rendered as a dropdown instead of a modal. If you were relying on the modal for any sort of customizations, these customizations will need to be adjusted to the new form factor.
New appearance prop keys were added to aid with customization, if desired:
cl-menuList__connectedAccounts
for styling the list of connected account addition optionscl-menuItem__connectedAccounts
for styling individual items in the connected account options listcl-menuList__web3Wallets
for styling the list of web3 wallet addition optionscl-menuItem__web3Wallets
for styling individual items in the web3 wallets options list
userButtonPopoverActionButtonText
customization id removed
userButtonPopoverActionButtonText
customization id removedThe userButtonPopoverActionButtonText
customization id has been removed, as the text for this button is now directly rendered inside the button rather than an extra wrapping element. The nested ids userButtonPopoverActionButtonText__signOut
and userButtonPopoverActionButtonText__manageAccount
have also been removed. Any styling that needs to apply to the text can be applied to its direct parent cl-userButtonPopoverActionButton
.
userButtonBox
is now a child of userButtonTrigger
userButtonBox
is now a child of userButtonTrigger
The parent-child relationship of the two elements userButtonTrigger
and userButtonBox
has been swapped. Previously, userButtonTrigger
was nested inside of userButtonBox
, and now userButtonBox
is nested inside of userButtonTrigger
. This change resolves some usability issues in <UserButton />
. If you are applying style customization to either of these elements, your customizations may need to be adjusted.
organizationSwitcherPopoverActionButtonText
customization id removed
organizationSwitcherPopoverActionButtonText
customization id removedThe organizationSwitcherPopoverActionButtonText
customization id has been removed, as the text for this button is now directly rendered inside the button rather than an extra wrapping element. The nested ids organizationSwitcherPopoverActionButtonText__manageOrganization
and organizationSwitcherPopoverActionButtonText__createOrganization
have also been removed. Any styling that needs to apply to the text can be applied to its direct parent cl-organizationSwitcherPopoverActionButton
.
Changes to the card
customization id
card
customization idThe card
customization id in the previous major version was the main and only container element for components. Outside the card
element, a new cardBox
id was introduced that allows more fine-grained style customization.
As a note, if you are changing the background color of card
, you will also need to also apply the same color on the footer
id as well. The footer
now gray by default, and it’s located outside card
, but inside cardBox
.
A footerItem
id was also added for more targeted styling of items inside the footer
.
Back button customization ids change on alternative 2fa methods page
The "back" button on the panel within <SignIn />
that lists out alternative two factor auth methods has changed location, and there have been some changes to the ids as a result of this:
headerBackIcon
has been removed, as there is no longer an associated iconheaderBackRow
has been renamed tobackRow
as it's no longer in the headerheaderBackLink
has been renamed tobackLink
as it's no longer in the header
button
-> organizationListCreateOrganizationActionButton
customization id
button
-> organizationListCreateOrganizationActionButton
customization idThe button
customization id was used only in one place, for a button to create a new organization in the <OrganizationList />
component. This id has been removed and replaced by the more appropriately named organizationListCreateOrganizationActionButton
customization id instead.
socialButtonsBlockButtonArrow
customization id removed
socialButtonsBlockButtonArrow
customization id removedSocial sign-in buttons in the new component designs no longer include arrows, so the socialButtonsBlockButtonArrow
customization id has been removed. You can use the socialButtonsIconButton
to apply custom styling to the social buttons if desired.
Identity preview avatar customization ids removed
When signing in with Clerk's <SignIn />
component, after entering a username or email the user is brought to a second pane where they can enter a second factor such as a password. On this pane, there is an area called "identity preview" that shows the username/email that they are entering a password/etc for. Previously, this area included the user's avatar, but this is no longer the case in updated designs. As such, the customization ids related to the user's avatar have been removed.
Changes to default variables
The default values of some appearance variables have changed which may impact your UI (if you are not already overriding them).
- The default
colorPrimary
value changed from#103FEF
to#2F3037
. As the new color is a dark grey, thecolorPrimary
of the dark theme was changed to#FFFFFF
. - The default
fontSize
value changed from1rem
to0.8125rem
- The default
fontWeight
values changed from{ normal: 400, medium: 500, bold: 600 }
to{ normal: 400, medium: 500, semibold: 600, bold: 700 }
.
New localization keys added
As part of the redesign of Clerk's components, a number of new localization keys have been added and can be seen along with their default english values in the code block below. If you do not supply translated values for these keys in your custom localization, they will fall back to the default english values specified below.
Removed localization keys
As part of the redesign of Clerk's components, a number of localization keys have been removed as they were no longer present in the new designs. You should remove any of these keys that are present in your localization object as they are no longer needed.
If you'd like to automate this, you can use the lodash omit function as such:
Localization keys changed
The values of some keys have been changed on the default en-US localization object. The list below shows you the new defaults (as of writing this guide) which you can either use or overwrite. If you have overridden these values, make sure to double check so you can be sure that your modifications are appropriate.
Feedback
Last updated on