From 43d7295c687cc4daa8895fb99f13bef045f26d39 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Tue, 18 Mar 2025 11:18:23 -0400
Subject: [PATCH 1/6] refactor(clerk-js): Add localization support to commerce
 components

---
 .../src/ui/components/Checkout/Checkout.tsx   |  2 +-
 .../components/Checkout/CheckoutComplete.tsx  | 39 +++++++++-------
 .../ui/components/Checkout/CheckoutForm.tsx   | 42 ++++++++---------
 .../ui/components/PricingTable/PlanCard.tsx   | 10 +++-
 .../clerk-js/src/ui/elements/Disclosure.tsx   | 10 ++--
 packages/clerk-js/src/ui/elements/Drawer.tsx  | 19 +++++---
 .../clerk-js/src/ui/elements/LineItems.tsx    | 46 ++++++++++---------
 .../src/ui/elements/SegmentedControl.tsx      |  9 ++--
 8 files changed, 100 insertions(+), 77 deletions(-)

diff --git a/packages/clerk-js/src/ui/components/Checkout/Checkout.tsx b/packages/clerk-js/src/ui/components/Checkout/Checkout.tsx
index 7d4e4bcb933..e22669613de 100644
--- a/packages/clerk-js/src/ui/components/Checkout/Checkout.tsx
+++ b/packages/clerk-js/src/ui/components/Checkout/Checkout.tsx
@@ -35,7 +35,7 @@ const AuthenticatedRoutes = withCoreUserGuard((props: __experimental_CheckoutPro
     >
       <Drawer.Overlay />
       <Drawer.Content>
-        <Drawer.Header title='Checkout' />
+        <Drawer.Header titleSlot='Checkout' />
         <CheckoutPage {...props} />
       </Drawer.Content>
     </Drawer.Root>
diff --git a/packages/clerk-js/src/ui/components/Checkout/CheckoutComplete.tsx b/packages/clerk-js/src/ui/components/Checkout/CheckoutComplete.tsx
index c44ff51e7ba..0e93ca59093 100644
--- a/packages/clerk-js/src/ui/components/Checkout/CheckoutComplete.tsx
+++ b/packages/clerk-js/src/ui/components/Checkout/CheckoutComplete.tsx
@@ -1,7 +1,7 @@
 import type { __experimental_CommerceCheckoutResource } from '@clerk/types';
 
 import { useCheckoutContext } from '../../contexts';
-import { Box, Button, descriptors, Heading, Icon, Span, Text } from '../../customizables';
+import { Box, Button, descriptors, Heading, Icon, localizationKeys, Span, Text } from '../../customizables';
 import { Drawer, LineItems } from '../../elements';
 import { Check } from '../../icons';
 
@@ -98,30 +98,35 @@ export const CheckoutComplete = ({ checkout }: { checkout: __experimental_Commer
       >
         <LineItems.Root>
           <LineItems.Group variant='secondary'>
-            <LineItems.Title>Total paid</LineItems.Title>
-            <LineItems.Description>
-              {checkout.invoice
-                ? `${checkout.invoice.totals.grandTotal.currencySymbol}${checkout.invoice.totals.grandTotal.amountFormatted}`
-                : '–'}
-            </LineItems.Description>
+            {/* TODO(@COMMERCE): needs localization */}
+            <LineItems.Title titleSlot='Total paid' />
+            <LineItems.Description
+              textSlot={
+                checkout.invoice
+                  ? `${checkout.invoice.totals.grandTotal.currencySymbol}${checkout.invoice.totals.grandTotal.amountFormatted}`
+                  : '–'
+              }
+            />
           </LineItems.Group>
           <LineItems.Group variant='secondary'>
             {/* TODO(@COMMERCE): needs localization */}
-            <LineItems.Title>Payment method</LineItems.Title>
-            <LineItems.Description>
-              {checkout.paymentSource ? `${checkout.paymentSource.cardType} ⋯ ${checkout.paymentSource.last4}` : '–'}
-            </LineItems.Description>
+            <LineItems.Title titleSlot='Payment method' />
+            <LineItems.Description
+              textSlot={
+                checkout.paymentSource ? `${checkout.paymentSource.cardType} ⋯ ${checkout.paymentSource.last4}` : '–'
+              }
+            />
           </LineItems.Group>
           <LineItems.Group variant='tertiary'>
             {/* TODO(@COMMERCE): needs localization */}
-            <LineItems.Title>Invoice ID</LineItems.Title>
-            <LineItems.Description>{checkout.invoice ? checkout.invoice.id : '–'}</LineItems.Description>
+            <LineItems.Title titleSlot='Invoice ID' />
+            <LineItems.Description textSlot={checkout.invoice ? checkout.invoice.id : '–'} />
           </LineItems.Group>
         </LineItems.Root>
-        <Button onClick={handleClose}>
-          {/* TODO(@COMMERCE): needs localization */}
-          Continue
-        </Button>
+        <Button
+          onClick={handleClose}
+          localizationKey={localizationKeys('formButtonPrimary')}
+        />
       </Drawer.Footer>
     </>
   );
diff --git a/packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx b/packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx
index eeee8a29933..3e1c63aa2f8 100644
--- a/packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx
+++ b/packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx
@@ -40,40 +40,36 @@ export const CheckoutForm = ({
       >
         <LineItems.Root>
           <LineItems.Group>
-            <LineItems.Title>{plan.name}</LineItems.Title>
+            <LineItems.Title titleSlot={plan.name} />
             {/* TODO(@Commerce): needs localization */}
-            <LineItems.Description suffix={`per month${planPeriod === 'annual' ? ', times 12 months' : ''}`}>
-              {plan.currencySymbol}
-              {planPeriod === 'month' ? plan.amountFormatted : plan.annualMonthlyAmountFormatted}
-            </LineItems.Description>
+            <LineItems.Description
+              textSlot={`${plan.currencySymbol} ${planPeriod === 'month' ? plan.amountFormatted : plan.annualMonthlyAmountFormatted}`}
+              suffixSlot={`per month${planPeriod === 'annual' ? ', times 12 months' : ''}`}
+            />
           </LineItems.Group>
           <LineItems.Group
             borderTop
             variant='tertiary'
           >
             {/* TODO(@Commerce): needs localization */}
-            <LineItems.Title>Subtotal</LineItems.Title>
-            <LineItems.Description>
-              {totals.subtotal.currencySymbol}
-              {totals.subtotal.amountFormatted}
-            </LineItems.Description>
+            <LineItems.Title titleSlot='Subtotal' />
+            <LineItems.Description textSlot={`${totals.subtotal.currencySymbol} ${totals.subtotal.amountFormatted}`} />
           </LineItems.Group>
           <LineItems.Group variant='tertiary'>
             {/* TODO(@Commerce): needs localization */}
-            <LineItems.Title>Tax</LineItems.Title>
-            <LineItems.Description>
-              {totals.taxTotal.currencySymbol}
-              {totals.taxTotal.amountFormatted}
-            </LineItems.Description>
+            <LineItems.Title titleSlot='Tax' />
+            <LineItems.Description textSlot={`${totals.taxTotal.currencySymbol} ${totals.taxTotal.amountFormatted}`} />
           </LineItems.Group>
           <LineItems.Group borderTop>
             {/* TODO(@Commerce): needs localization */}
-            <LineItems.Title>Total{totals.totalDueNow ? ' Due Today' : ''}</LineItems.Title>
-            <LineItems.Description>
-              {totals.totalDueNow
-                ? `${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`
-                : `${totals.grandTotal.currencySymbol}${totals.grandTotal.amountFormatted}`}
-            </LineItems.Description>
+            <LineItems.Title titleSlot={`Total${totals.totalDueNow ? ' Due Today' : ''}`} />
+            <LineItems.Description
+              textSlot={`${
+                totals.totalDueNow
+                  ? `${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`
+                  : `${totals.grandTotal.currencySymbol}${totals.grandTotal.amountFormatted}`
+              }`}
+            />
           </LineItems.Group>
         </LineItems.Root>
       </Box>
@@ -201,7 +197,7 @@ const CheckoutFormElements = ({
             onOpenChange={setOpenAccountFundsDropDown}
           >
             {/* TODO(@Commerce): needs localization */}
-            <Disclosure.Trigger>Account Funds</Disclosure.Trigger>
+            <Disclosure.Trigger textSlot='Account Funds' />
             <Disclosure.Content>
               <Col gap={3}>
                 <PaymentSourceMethods
@@ -222,7 +218,7 @@ const CheckoutFormElements = ({
         onOpenChange={setOpenAddNewSourceDropDown}
       >
         {/* TODO(@Commerce): needs localization */}
-        <Disclosure.Trigger>Add a New Payment Source</Disclosure.Trigger>
+        <Disclosure.Trigger textSlot='Add a New Payment Source' />
         <Disclosure.Content>
           <StripePaymentMethods
             totalDueNow={checkout.totals.totalDueNow || checkout.totals.grandTotal}
diff --git a/packages/clerk-js/src/ui/components/PricingTable/PlanCard.tsx b/packages/clerk-js/src/ui/components/PricingTable/PlanCard.tsx
index 691c52b4742..928540e9af6 100644
--- a/packages/clerk-js/src/ui/components/PricingTable/PlanCard.tsx
+++ b/packages/clerk-js/src/ui/components/PricingTable/PlanCard.tsx
@@ -325,8 +325,14 @@ export const PlanCardHeader = React.forwardRef<HTMLDivElement, PlanCardHeaderPro
             value={planPeriod}
             onChange={value => setPlanPeriod(value as PlanPeriod)}
           >
-            <SegmentedControl.Button value='month'>Monthly</SegmentedControl.Button>
-            <SegmentedControl.Button value='annual'>Annually</SegmentedControl.Button>
+            <SegmentedControl.Button
+              value='month'
+              textSlot='Monthly'
+            />
+            <SegmentedControl.Button
+              value='annual'
+              textSlot='Annually'
+            />
           </SegmentedControl.Root>
         </Box>
       ) : null}
diff --git a/packages/clerk-js/src/ui/elements/Disclosure.tsx b/packages/clerk-js/src/ui/elements/Disclosure.tsx
index 6731e394716..5b7b4bb2cb0 100644
--- a/packages/clerk-js/src/ui/elements/Disclosure.tsx
+++ b/packages/clerk-js/src/ui/elements/Disclosure.tsx
@@ -1,6 +1,7 @@
 import * as React from 'react';
 
-import { Box, descriptors, Icon, SimpleButton, useAppearance } from '../customizables';
+import type { LocalizationKey } from '../customizables';
+import { Box, descriptors, Icon, SimpleButton, Span, useAppearance } from '../customizables';
 import { usePrefersReducedMotion } from '../hooks';
 import { ChevronDown } from '../icons';
 import type { ThemableCssProp } from '../styledSystem';
@@ -72,10 +73,11 @@ Root.displayName = 'Disclosure.Root';
  * -----------------------------------------------------------------------------------------------*/
 
 interface TriggerProps {
-  children: React.ReactNode;
+  textKey?: LocalizationKey;
+  textSlot?: React.ReactNode;
 }
 
-const Trigger = React.forwardRef<HTMLButtonElement, TriggerProps>(({ children }, ref) => {
+const Trigger = React.forwardRef<HTMLButtonElement, TriggerProps>(({ textKey, textSlot }, ref) => {
   const context = React.useContext(DisclosureContext);
   if (!context) {
     throw new Error('Disclosure.Trigger must be used within Disclosure.Root');
@@ -99,7 +101,7 @@ const Trigger = React.forwardRef<HTMLButtonElement, TriggerProps>(({ children },
         zIndex: 2,
       })}
     >
-      {children}
+      <Span localizationKey={textKey}>{textSlot}</Span>
       <Icon
         icon={ChevronDown}
         colorScheme='neutral'
diff --git a/packages/clerk-js/src/ui/elements/Drawer.tsx b/packages/clerk-js/src/ui/elements/Drawer.tsx
index 05b3ab2c9de..b9ec9c2695e 100644
--- a/packages/clerk-js/src/ui/elements/Drawer.tsx
+++ b/packages/clerk-js/src/ui/elements/Drawer.tsx
@@ -14,6 +14,7 @@ import {
 import * as React from 'react';
 
 import { transitionDurationValues, transitionTiming } from '../../ui/foundations/transitions';
+import type { LocalizationKey } from '../customizables';
 import { Box, descriptors, Flex, Heading, Icon, Span, useAppearance } from '../customizables';
 import { usePrefersReducedMotion } from '../hooks';
 import { useScrollLock } from '../hooks/useScrollLock';
@@ -263,12 +264,14 @@ Overlay.displayName = 'Drawer.Content';
  * -----------------------------------------------------------------------------------------------*/
 
 interface HeaderProps {
-  title?: string;
+  titleKey?: LocalizationKey;
+  titleSlot?: React.ReactNode;
   children?: React.ReactNode;
   sx?: ThemableCssProp;
 }
 
-const Header = React.forwardRef<HTMLDivElement, HeaderProps>(({ title, children, sx }, ref) => {
+const Header = React.forwardRef<HTMLDivElement, HeaderProps>(({ titleKey, titleSlot, children, sx }, ref) => {
+  const hasTitle = titleKey || titleSlot;
   return (
     <Box
       ref={ref}
@@ -286,15 +289,16 @@ const Header = React.forwardRef<HTMLDivElement, HeaderProps>(({ title, children,
           borderBlockEndColor: t.colors.$neutralAlpha100,
           borderStartStartRadius: t.radii.$xl,
           borderStartEndRadius: t.radii.$xl,
-          paddingBlock: title ? t.space.$3 : undefined,
-          paddingInline: title ? t.space.$4 : undefined,
+          paddingBlock: hasTitle ? t.space.$3 : undefined,
+          paddingInline: hasTitle ? t.space.$4 : undefined,
         }),
         sx,
       ]}
     >
-      {title ? (
+      {hasTitle ? (
         <>
           <Heading
+            localizationKey={titleKey}
             as='h2'
             elementDescriptor={descriptors.drawerTitle}
             textVariant='h2'
@@ -302,7 +306,7 @@ const Header = React.forwardRef<HTMLDivElement, HeaderProps>(({ title, children,
               alignSelf: 'center',
             }}
           >
-            {title}
+            {titleSlot}
           </Heading>
           <Close />
         </>
@@ -416,6 +420,9 @@ interface ConfirmationProps {
   onOpenChange: (open: boolean) => void;
   children: React.ReactNode;
   actionsSlot: React.ReactNode;
+  /**
+   * @see https://floating-ui.com/docs/userole
+   */
   roleProps?: UseRoleProps;
 }
 
diff --git a/packages/clerk-js/src/ui/elements/LineItems.tsx b/packages/clerk-js/src/ui/elements/LineItems.tsx
index 9f6e6263ec5..8995ffdf2b0 100644
--- a/packages/clerk-js/src/ui/elements/LineItems.tsx
+++ b/packages/clerk-js/src/ui/elements/LineItems.tsx
@@ -1,5 +1,6 @@
 import * as React from 'react';
 
+import type { LocalizationKey } from '../customizables';
 import { Box, Dd, descriptors, Dl, Dt, Span } from '../customizables';
 import { common } from '../styledSystem';
 
@@ -76,11 +77,13 @@ function Group({ children, borderTop = false, variant = 'primary' }: GroupProps)
  * -----------------------------------------------------------------------------------------------*/
 
 interface TitleProps {
-  children: React.ReactNode;
-  description?: React.ReactNode;
+  titleKey?: LocalizationKey;
+  titleSlot?: React.ReactNode;
+  descriptionKey?: LocalizationKey;
+  descriptionSlot?: React.ReactNode;
 }
 
-function Title({ children, description }: TitleProps) {
+function Title({ titleKey, titleSlot, descriptionKey, descriptionSlot }: TitleProps) {
   const context = React.useContext(GroupContext);
   if (!context) {
     throw new Error('LineItems.Title must be used within LineItems.Group');
@@ -98,16 +101,17 @@ function Title({ children, description }: TitleProps) {
         ...common.textVariants(t)[textVariant],
       })}
     >
-      {children}
-      {description ? (
+      <Span localizationKey={titleKey}>{titleSlot}</Span>
+      {descriptionKey || descriptionSlot ? (
         <Span
+          localizationKey={descriptionKey}
           elementDescriptor={descriptors.lineItemsTitleDescription}
           sx={t => ({
             fontSize: t.fontSizes.$sm,
             color: t.colors.$colorTextSecondary,
           })}
         >
-          {description}
+          {descriptionSlot}
         </Span>
       ) : null}
     </Dt>
@@ -119,18 +123,15 @@ function Title({ children, description }: TitleProps) {
  * -----------------------------------------------------------------------------------------------*/
 
 interface DescriptionProps {
-  children: React.ReactNode;
-  /**
-   * Render a piece of text before the description text.
-   */
-  prefix?: React.ReactNode;
-  /**
-   * Render a note below the description text.
-   */
-  suffix?: React.ReactNode;
+  textKey?: LocalizationKey;
+  textSlot?: React.ReactNode;
+  prefixKey?: LocalizationKey;
+  prefixSlot?: React.ReactNode;
+  suffixKey?: LocalizationKey;
+  suffixSlot?: React.ReactNode;
 }
 
-function Description({ children, prefix, suffix }: DescriptionProps) {
+function Description({ textKey, textSlot, prefixKey, prefixSlot, suffixKey, suffixSlot }: DescriptionProps) {
   const context = React.useContext(GroupContext);
   if (!context) {
     throw new Error('LineItems.Description must be used within LineItems.Group');
@@ -155,35 +156,38 @@ function Description({ children, prefix, suffix }: DescriptionProps) {
           gap: t.space.$1,
         })}
       >
-        {prefix ? (
+        {prefixKey || prefixSlot ? (
           <Span
+            localizationKey={prefixKey}
             elementDescriptor={descriptors.lineItemsDescriptionPrefix}
             sx={t => ({
               color: t.colors.$colorTextSecondary,
               ...common.textVariants(t).caption,
             })}
           >
-            {prefix}
+            {prefixSlot}
           </Span>
         ) : null}
         <Span
+          localizationKey={textKey}
           elementDescriptor={descriptors.lineItemsDescriptionText}
           sx={t => ({
             ...common.textVariants(t).body,
           })}
         >
-          {children}
+          {textSlot}
         </Span>
       </Span>
-      {suffix ? (
+      {suffixKey || suffixSlot ? (
         <Span
+          localizationKey={suffixKey}
           elementDescriptor={descriptors.lineItemsDescriptionSuffix}
           sx={t => ({
             color: t.colors.$colorTextSecondary,
             ...common.textVariants(t).caption,
           })}
         >
-          {suffix}
+          {suffixSlot}
         </Span>
       ) : null}
     </Dd>
diff --git a/packages/clerk-js/src/ui/elements/SegmentedControl.tsx b/packages/clerk-js/src/ui/elements/SegmentedControl.tsx
index c3f9d2d03ae..173e9e7b7bf 100644
--- a/packages/clerk-js/src/ui/elements/SegmentedControl.tsx
+++ b/packages/clerk-js/src/ui/elements/SegmentedControl.tsx
@@ -1,6 +1,7 @@
 import { Composite, CompositeItem } from '@floating-ui/react';
 import React, { createContext, useContext, useState } from 'react';
 
+import type { LocalizationKey } from '../customizables';
 import { descriptors, Flex, SimpleButton } from '../customizables';
 
 /* -------------------------------------------------------------------------------------------------
@@ -83,11 +84,12 @@ Root.displayName = 'SegmentedControl.Root';
  * -----------------------------------------------------------------------------------------------*/
 
 interface ButtonProps {
-  children: React.ReactNode;
+  textKey?: LocalizationKey;
+  textSlot?: React.ReactNode;
   value: string;
 }
 
-const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(({ children, value }, ref) => {
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(({ textKey, textSlot, value }, ref) => {
   const { currentValue, onValueChange } = useSegmentedControlContext();
   const isSelected = value === currentValue;
 
@@ -98,6 +100,7 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(({ children, val
           <SimpleButton
             ref={ref}
             {...compProps}
+            localizationKey={textKey}
             elementDescriptor={descriptors.segmentedControlButton}
             variant='unstyled'
             role='radio'
@@ -119,7 +122,7 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(({ children, val
               },
             })}
           >
-            {children}
+            {textSlot}
           </SimpleButton>
         );
       }}

From dfcbfe60167f767a9f425f0ea546f29880d8f6ce Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Tue, 18 Mar 2025 11:24:33 -0400
Subject: [PATCH 2/6] add changeset

---
 .changeset/chilled-garlics-knock.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/chilled-garlics-knock.md

diff --git a/.changeset/chilled-garlics-knock.md b/.changeset/chilled-garlics-knock.md
new file mode 100644
index 00000000000..962fa085af5
--- /dev/null
+++ b/.changeset/chilled-garlics-knock.md
@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Add support for localizationKeys within commerce components.

From aed0b08799cb5a0caa9cf8007982e65bffde98e5 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Tue, 18 Mar 2025 13:40:44 -0400
Subject: [PATCH 3/6] use string | LocalizationKey approach

---
 .../src/ui/components/Checkout/Checkout.tsx   |  2 +-
 .../components/Checkout/CheckoutComplete.tsx  | 12 ++---
 .../ui/components/Checkout/CheckoutForm.tsx   | 22 ++++----
 .../ui/components/PricingTable/PlanCard.tsx   |  4 +-
 .../clerk-js/src/ui/elements/Disclosure.tsx   |  7 ++-
 packages/clerk-js/src/ui/elements/Drawer.tsx  | 18 +++----
 .../clerk-js/src/ui/elements/LineItems.tsx    | 50 +++++++------------
 .../src/ui/elements/SegmentedControl.tsx      | 11 ++--
 8 files changed, 53 insertions(+), 73 deletions(-)

diff --git a/packages/clerk-js/src/ui/components/Checkout/Checkout.tsx b/packages/clerk-js/src/ui/components/Checkout/Checkout.tsx
index e22669613de..7d4e4bcb933 100644
--- a/packages/clerk-js/src/ui/components/Checkout/Checkout.tsx
+++ b/packages/clerk-js/src/ui/components/Checkout/Checkout.tsx
@@ -35,7 +35,7 @@ const AuthenticatedRoutes = withCoreUserGuard((props: __experimental_CheckoutPro
     >
       <Drawer.Overlay />
       <Drawer.Content>
-        <Drawer.Header titleSlot='Checkout' />
+        <Drawer.Header title='Checkout' />
         <CheckoutPage {...props} />
       </Drawer.Content>
     </Drawer.Root>
diff --git a/packages/clerk-js/src/ui/components/Checkout/CheckoutComplete.tsx b/packages/clerk-js/src/ui/components/Checkout/CheckoutComplete.tsx
index 0e93ca59093..dea80762f82 100644
--- a/packages/clerk-js/src/ui/components/Checkout/CheckoutComplete.tsx
+++ b/packages/clerk-js/src/ui/components/Checkout/CheckoutComplete.tsx
@@ -99,9 +99,9 @@ export const CheckoutComplete = ({ checkout }: { checkout: __experimental_Commer
         <LineItems.Root>
           <LineItems.Group variant='secondary'>
             {/* TODO(@COMMERCE): needs localization */}
-            <LineItems.Title titleSlot='Total paid' />
+            <LineItems.Title title='Total paid' />
             <LineItems.Description
-              textSlot={
+              text={
                 checkout.invoice
                   ? `${checkout.invoice.totals.grandTotal.currencySymbol}${checkout.invoice.totals.grandTotal.amountFormatted}`
                   : '–'
@@ -110,17 +110,17 @@ export const CheckoutComplete = ({ checkout }: { checkout: __experimental_Commer
           </LineItems.Group>
           <LineItems.Group variant='secondary'>
             {/* TODO(@COMMERCE): needs localization */}
-            <LineItems.Title titleSlot='Payment method' />
+            <LineItems.Title title='Payment method' />
             <LineItems.Description
-              textSlot={
+              text={
                 checkout.paymentSource ? `${checkout.paymentSource.cardType} ⋯ ${checkout.paymentSource.last4}` : '–'
               }
             />
           </LineItems.Group>
           <LineItems.Group variant='tertiary'>
             {/* TODO(@COMMERCE): needs localization */}
-            <LineItems.Title titleSlot='Invoice ID' />
-            <LineItems.Description textSlot={checkout.invoice ? checkout.invoice.id : '–'} />
+            <LineItems.Title title='Invoice ID' />
+            <LineItems.Description text={checkout.invoice ? checkout.invoice.id : '–'} />
           </LineItems.Group>
         </LineItems.Root>
         <Button
diff --git a/packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx b/packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx
index 3e1c63aa2f8..6edeb1167f1 100644
--- a/packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx
+++ b/packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx
@@ -40,11 +40,11 @@ export const CheckoutForm = ({
       >
         <LineItems.Root>
           <LineItems.Group>
-            <LineItems.Title titleSlot={plan.name} />
+            <LineItems.Title title={plan.name} />
             {/* TODO(@Commerce): needs localization */}
             <LineItems.Description
-              textSlot={`${plan.currencySymbol} ${planPeriod === 'month' ? plan.amountFormatted : plan.annualMonthlyAmountFormatted}`}
-              suffixSlot={`per month${planPeriod === 'annual' ? ', times 12 months' : ''}`}
+              text={`${plan.currencySymbol} ${planPeriod === 'month' ? plan.amountFormatted : plan.annualMonthlyAmountFormatted}`}
+              suffix={`per month${planPeriod === 'annual' ? ', times 12 months' : ''}`}
             />
           </LineItems.Group>
           <LineItems.Group
@@ -52,19 +52,19 @@ export const CheckoutForm = ({
             variant='tertiary'
           >
             {/* TODO(@Commerce): needs localization */}
-            <LineItems.Title titleSlot='Subtotal' />
-            <LineItems.Description textSlot={`${totals.subtotal.currencySymbol} ${totals.subtotal.amountFormatted}`} />
+            <LineItems.Title title='Subtotal' />
+            <LineItems.Description text={`${totals.subtotal.currencySymbol} ${totals.subtotal.amountFormatted}`} />
           </LineItems.Group>
           <LineItems.Group variant='tertiary'>
             {/* TODO(@Commerce): needs localization */}
-            <LineItems.Title titleSlot='Tax' />
-            <LineItems.Description textSlot={`${totals.taxTotal.currencySymbol} ${totals.taxTotal.amountFormatted}`} />
+            <LineItems.Title title='Tax' />
+            <LineItems.Description text={`${totals.taxTotal.currencySymbol} ${totals.taxTotal.amountFormatted}`} />
           </LineItems.Group>
           <LineItems.Group borderTop>
             {/* TODO(@Commerce): needs localization */}
-            <LineItems.Title titleSlot={`Total${totals.totalDueNow ? ' Due Today' : ''}`} />
+            <LineItems.Title title={`Total${totals.totalDueNow ? ' Due Today' : ''}`} />
             <LineItems.Description
-              textSlot={`${
+              text={`${
                 totals.totalDueNow
                   ? `${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`
                   : `${totals.grandTotal.currencySymbol}${totals.grandTotal.amountFormatted}`
@@ -197,7 +197,7 @@ const CheckoutFormElements = ({
             onOpenChange={setOpenAccountFundsDropDown}
           >
             {/* TODO(@Commerce): needs localization */}
-            <Disclosure.Trigger textSlot='Account Funds' />
+            <Disclosure.Trigger text='Account Funds' />
             <Disclosure.Content>
               <Col gap={3}>
                 <PaymentSourceMethods
@@ -218,7 +218,7 @@ const CheckoutFormElements = ({
         onOpenChange={setOpenAddNewSourceDropDown}
       >
         {/* TODO(@Commerce): needs localization */}
-        <Disclosure.Trigger textSlot='Add a New Payment Source' />
+        <Disclosure.Trigger text='Add a New Payment Source' />
         <Disclosure.Content>
           <StripePaymentMethods
             totalDueNow={checkout.totals.totalDueNow || checkout.totals.grandTotal}
diff --git a/packages/clerk-js/src/ui/components/PricingTable/PlanCard.tsx b/packages/clerk-js/src/ui/components/PricingTable/PlanCard.tsx
index 928540e9af6..889987e2702 100644
--- a/packages/clerk-js/src/ui/components/PricingTable/PlanCard.tsx
+++ b/packages/clerk-js/src/ui/components/PricingTable/PlanCard.tsx
@@ -327,11 +327,11 @@ export const PlanCardHeader = React.forwardRef<HTMLDivElement, PlanCardHeaderPro
           >
             <SegmentedControl.Button
               value='month'
-              textSlot='Monthly'
+              text='Monthly'
             />
             <SegmentedControl.Button
               value='annual'
-              textSlot='Annually'
+              text='Annually'
             />
           </SegmentedControl.Root>
         </Box>
diff --git a/packages/clerk-js/src/ui/elements/Disclosure.tsx b/packages/clerk-js/src/ui/elements/Disclosure.tsx
index 5b7b4bb2cb0..bd29ec44de7 100644
--- a/packages/clerk-js/src/ui/elements/Disclosure.tsx
+++ b/packages/clerk-js/src/ui/elements/Disclosure.tsx
@@ -73,11 +73,10 @@ Root.displayName = 'Disclosure.Root';
  * -----------------------------------------------------------------------------------------------*/
 
 interface TriggerProps {
-  textKey?: LocalizationKey;
-  textSlot?: React.ReactNode;
+  text?: string | LocalizationKey;
 }
 
-const Trigger = React.forwardRef<HTMLButtonElement, TriggerProps>(({ textKey, textSlot }, ref) => {
+const Trigger = React.forwardRef<HTMLButtonElement, TriggerProps>(({ text }, ref) => {
   const context = React.useContext(DisclosureContext);
   if (!context) {
     throw new Error('Disclosure.Trigger must be used within Disclosure.Root');
@@ -101,7 +100,7 @@ const Trigger = React.forwardRef<HTMLButtonElement, TriggerProps>(({ textKey, te
         zIndex: 2,
       })}
     >
-      <Span localizationKey={textKey}>{textSlot}</Span>
+      <Span localizationKey={text} />
       <Icon
         icon={ChevronDown}
         colorScheme='neutral'
diff --git a/packages/clerk-js/src/ui/elements/Drawer.tsx b/packages/clerk-js/src/ui/elements/Drawer.tsx
index b9ec9c2695e..b7552cdf102 100644
--- a/packages/clerk-js/src/ui/elements/Drawer.tsx
+++ b/packages/clerk-js/src/ui/elements/Drawer.tsx
@@ -264,14 +264,12 @@ Overlay.displayName = 'Drawer.Content';
  * -----------------------------------------------------------------------------------------------*/
 
 interface HeaderProps {
-  titleKey?: LocalizationKey;
-  titleSlot?: React.ReactNode;
+  title?: string | LocalizationKey;
   children?: React.ReactNode;
   sx?: ThemableCssProp;
 }
 
-const Header = React.forwardRef<HTMLDivElement, HeaderProps>(({ titleKey, titleSlot, children, sx }, ref) => {
-  const hasTitle = titleKey || titleSlot;
+const Header = React.forwardRef<HTMLDivElement, HeaderProps>(({ title, children, sx }, ref) => {
   return (
     <Box
       ref={ref}
@@ -289,25 +287,23 @@ const Header = React.forwardRef<HTMLDivElement, HeaderProps>(({ titleKey, titleS
           borderBlockEndColor: t.colors.$neutralAlpha100,
           borderStartStartRadius: t.radii.$xl,
           borderStartEndRadius: t.radii.$xl,
-          paddingBlock: hasTitle ? t.space.$3 : undefined,
-          paddingInline: hasTitle ? t.space.$4 : undefined,
+          paddingBlock: title ? t.space.$3 : undefined,
+          paddingInline: title ? t.space.$4 : undefined,
         }),
         sx,
       ]}
     >
-      {hasTitle ? (
+      {title ? (
         <>
           <Heading
-            localizationKey={titleKey}
+            localizationKey={title}
             as='h2'
             elementDescriptor={descriptors.drawerTitle}
             textVariant='h2'
             sx={{
               alignSelf: 'center',
             }}
-          >
-            {titleSlot}
-          </Heading>
+          />
           <Close />
         </>
       ) : (
diff --git a/packages/clerk-js/src/ui/elements/LineItems.tsx b/packages/clerk-js/src/ui/elements/LineItems.tsx
index 8995ffdf2b0..0e3e3dbb226 100644
--- a/packages/clerk-js/src/ui/elements/LineItems.tsx
+++ b/packages/clerk-js/src/ui/elements/LineItems.tsx
@@ -77,13 +77,12 @@ function Group({ children, borderTop = false, variant = 'primary' }: GroupProps)
  * -----------------------------------------------------------------------------------------------*/
 
 interface TitleProps {
-  titleKey?: LocalizationKey;
-  titleSlot?: React.ReactNode;
-  descriptionKey?: LocalizationKey;
+  title?: string | LocalizationKey;
+  description?: string | LocalizationKey;
   descriptionSlot?: React.ReactNode;
 }
 
-function Title({ titleKey, titleSlot, descriptionKey, descriptionSlot }: TitleProps) {
+function Title({ title, description }: TitleProps) {
   const context = React.useContext(GroupContext);
   if (!context) {
     throw new Error('LineItems.Title must be used within LineItems.Group');
@@ -101,18 +100,16 @@ function Title({ titleKey, titleSlot, descriptionKey, descriptionSlot }: TitlePr
         ...common.textVariants(t)[textVariant],
       })}
     >
-      <Span localizationKey={titleKey}>{titleSlot}</Span>
-      {descriptionKey || descriptionSlot ? (
+      <Span localizationKey={title} />
+      {description ? (
         <Span
-          localizationKey={descriptionKey}
+          localizationKey={description}
           elementDescriptor={descriptors.lineItemsTitleDescription}
           sx={t => ({
             fontSize: t.fontSizes.$sm,
             color: t.colors.$colorTextSecondary,
           })}
-        >
-          {descriptionSlot}
-        </Span>
+        />
       ) : null}
     </Dt>
   );
@@ -123,15 +120,12 @@ function Title({ titleKey, titleSlot, descriptionKey, descriptionSlot }: TitlePr
  * -----------------------------------------------------------------------------------------------*/
 
 interface DescriptionProps {
-  textKey?: LocalizationKey;
-  textSlot?: React.ReactNode;
-  prefixKey?: LocalizationKey;
-  prefixSlot?: React.ReactNode;
-  suffixKey?: LocalizationKey;
-  suffixSlot?: React.ReactNode;
+  text?: string | LocalizationKey;
+  prefix?: string | LocalizationKey;
+  suffix?: string | LocalizationKey;
 }
 
-function Description({ textKey, textSlot, prefixKey, prefixSlot, suffixKey, suffixSlot }: DescriptionProps) {
+function Description({ text, prefix, suffix }: DescriptionProps) {
   const context = React.useContext(GroupContext);
   if (!context) {
     throw new Error('LineItems.Description must be used within LineItems.Group');
@@ -156,39 +150,33 @@ function Description({ textKey, textSlot, prefixKey, prefixSlot, suffixKey, suff
           gap: t.space.$1,
         })}
       >
-        {prefixKey || prefixSlot ? (
+        {prefix ? (
           <Span
-            localizationKey={prefixKey}
+            localizationKey={prefix}
             elementDescriptor={descriptors.lineItemsDescriptionPrefix}
             sx={t => ({
               color: t.colors.$colorTextSecondary,
               ...common.textVariants(t).caption,
             })}
-          >
-            {prefixSlot}
-          </Span>
+          />
         ) : null}
         <Span
-          localizationKey={textKey}
+          localizationKey={text}
           elementDescriptor={descriptors.lineItemsDescriptionText}
           sx={t => ({
             ...common.textVariants(t).body,
           })}
-        >
-          {textSlot}
-        </Span>
+        />
       </Span>
-      {suffixKey || suffixSlot ? (
+      {suffix ? (
         <Span
-          localizationKey={suffixKey}
+          localizationKey={suffix}
           elementDescriptor={descriptors.lineItemsDescriptionSuffix}
           sx={t => ({
             color: t.colors.$colorTextSecondary,
             ...common.textVariants(t).caption,
           })}
-        >
-          {suffixSlot}
-        </Span>
+        />
       ) : null}
     </Dd>
   );
diff --git a/packages/clerk-js/src/ui/elements/SegmentedControl.tsx b/packages/clerk-js/src/ui/elements/SegmentedControl.tsx
index 173e9e7b7bf..44f3d637bfb 100644
--- a/packages/clerk-js/src/ui/elements/SegmentedControl.tsx
+++ b/packages/clerk-js/src/ui/elements/SegmentedControl.tsx
@@ -84,12 +84,11 @@ Root.displayName = 'SegmentedControl.Root';
  * -----------------------------------------------------------------------------------------------*/
 
 interface ButtonProps {
-  textKey?: LocalizationKey;
-  textSlot?: React.ReactNode;
+  text: string | LocalizationKey;
   value: string;
 }
 
-const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(({ textKey, textSlot, value }, ref) => {
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(({ text, value }, ref) => {
   const { currentValue, onValueChange } = useSegmentedControlContext();
   const isSelected = value === currentValue;
 
@@ -100,7 +99,7 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(({ textKey, text
           <SimpleButton
             ref={ref}
             {...compProps}
-            localizationKey={textKey}
+            localizationKey={text}
             elementDescriptor={descriptors.segmentedControlButton}
             variant='unstyled'
             role='radio'
@@ -121,9 +120,7 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(({ textKey, text
                 zIndex: 2,
               },
             })}
-          >
-            {textSlot}
-          </SimpleButton>
+          />
         );
       }}
     />

From 3640d41c35d7aa31bca6b718477a257d8a42fe3e Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Tue, 18 Mar 2025 13:42:07 -0400
Subject: [PATCH 4/6] remove

---
 packages/clerk-js/src/ui/elements/LineItems.tsx | 1 -
 1 file changed, 1 deletion(-)

diff --git a/packages/clerk-js/src/ui/elements/LineItems.tsx b/packages/clerk-js/src/ui/elements/LineItems.tsx
index 0e3e3dbb226..51e222b2b24 100644
--- a/packages/clerk-js/src/ui/elements/LineItems.tsx
+++ b/packages/clerk-js/src/ui/elements/LineItems.tsx
@@ -79,7 +79,6 @@ function Group({ children, borderTop = false, variant = 'primary' }: GroupProps)
 interface TitleProps {
   title?: string | LocalizationKey;
   description?: string | LocalizationKey;
-  descriptionSlot?: React.ReactNode;
 }
 
 function Title({ title, description }: TitleProps) {

From 6561d781ca93525870a85c6f8748154b83b1c330 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Tue, 18 Mar 2025 13:47:29 -0400
Subject: [PATCH 5/6] remove optional

---
 packages/clerk-js/src/ui/elements/Disclosure.tsx | 2 +-
 packages/clerk-js/src/ui/elements/LineItems.tsx  | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/clerk-js/src/ui/elements/Disclosure.tsx b/packages/clerk-js/src/ui/elements/Disclosure.tsx
index bd29ec44de7..cf1a4a31749 100644
--- a/packages/clerk-js/src/ui/elements/Disclosure.tsx
+++ b/packages/clerk-js/src/ui/elements/Disclosure.tsx
@@ -73,7 +73,7 @@ Root.displayName = 'Disclosure.Root';
  * -----------------------------------------------------------------------------------------------*/
 
 interface TriggerProps {
-  text?: string | LocalizationKey;
+  text: string | LocalizationKey;
 }
 
 const Trigger = React.forwardRef<HTMLButtonElement, TriggerProps>(({ text }, ref) => {
diff --git a/packages/clerk-js/src/ui/elements/LineItems.tsx b/packages/clerk-js/src/ui/elements/LineItems.tsx
index 51e222b2b24..4fb365953d4 100644
--- a/packages/clerk-js/src/ui/elements/LineItems.tsx
+++ b/packages/clerk-js/src/ui/elements/LineItems.tsx
@@ -77,7 +77,7 @@ function Group({ children, borderTop = false, variant = 'primary' }: GroupProps)
  * -----------------------------------------------------------------------------------------------*/
 
 interface TitleProps {
-  title?: string | LocalizationKey;
+  title: string | LocalizationKey;
   description?: string | LocalizationKey;
 }
 
@@ -119,7 +119,7 @@ function Title({ title, description }: TitleProps) {
  * -----------------------------------------------------------------------------------------------*/
 
 interface DescriptionProps {
-  text?: string | LocalizationKey;
+  text: string | LocalizationKey;
   prefix?: string | LocalizationKey;
   suffix?: string | LocalizationKey;
 }

From 0b1a31fd626b20957420e8aed9c71cf377eeffab Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Tue, 18 Mar 2025 14:22:37 -0400
Subject: [PATCH 6/6] Update PlanCard.tsx

---
 packages/clerk-js/src/ui/components/PricingTable/PlanCard.tsx | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/clerk-js/src/ui/components/PricingTable/PlanCard.tsx b/packages/clerk-js/src/ui/components/PricingTable/PlanCard.tsx
index 889987e2702..cda2191c97d 100644
--- a/packages/clerk-js/src/ui/components/PricingTable/PlanCard.tsx
+++ b/packages/clerk-js/src/ui/components/PricingTable/PlanCard.tsx
@@ -327,10 +327,12 @@ export const PlanCardHeader = React.forwardRef<HTMLDivElement, PlanCardHeaderPro
           >
             <SegmentedControl.Button
               value='month'
+              // TODO(@Commerce): needs localization
               text='Monthly'
             />
             <SegmentedControl.Button
               value='annual'
+              // TODO(@Commerce): needs localization
               text='Annually'
             />
           </SegmentedControl.Root>