clerk · wobsoriano · Aug 19, 2024 · Aug 15, 2024 · Aug 15, 2024 · Aug 15, 2024
diff --git a/.changeset/eighty-timers-march.md b/.changeset/eighty-timers-march.md
@@ -0,0 +1,5 @@
+---
+"@clerk/astro": minor
+---
+
+Add support for custom menu items in the `<UserButton />` Astro component.
diff --git a/integration/presets/astro.ts b/integration/presets/astro.ts
@@ -9,7 +9,10 @@ const astroNode = applicationConfig()
  .setName('astro-node')
  .useTemplate(templates['astro-node'])
  .setEnvFormatter('public', key => `PUBLIC_${key}`)
- .addScript('setup', 'npm i')
+ // When creating symlinks, the Astro vite plugin is unable to process `<script>` tags.
+ // Without `--install-link`, it throws this error:
+ // https://github.com/withastro/astro/blob/cb98b74881355de9ec9d90a613a3f1d27d154463/packages/astro/src/vite-plugin-astro/index.ts#L114
+ .addScript('setup', 'npm i --install-links')
  .addScript('dev', 'npm run dev')
  .addScript('build', 'npm run build')
  .addScript('serve', 'npm run preview')

diff --git a/integration/templates/astro-node/src/components/CustomUserButton.astro b/integration/templates/astro-node/src/components/CustomUserButton.astro
@@ -0,0 +1,26 @@
+---
+import { UserButton } from '@clerk/astro/components';
+---
+
+<UserButton afterSignOutUrl="/">
+ <UserButton.MenuItems>
+ <UserButton.Action label="signOut" />
+ <UserButton.Action label="manageAccount" />
+ <UserButton.Link label="Custom link" href="/user">
+ <div slot="label-icon">Icon</div>
+ </UserButton.Link>
+ <UserButton.Action label="Custom action" open="terms">
+ <div slot="label-icon">Icon</div>
+ </UserButton.Action>
+ <UserButton.Action label="Custom click" clickIdentifier="custom_click">
+ <div slot="label-icon">Icon</div>
+ </UserButton.Action>
+ </UserButton.MenuItems>
+ <UserButton.UserProfilePage label="Terms" url="terms">
+ <div slot="label-icon">Icon</div>
+ <div>
+ <h1>Custom Terms Page</h1>
+ <p>This is the custom terms page</p>
+ </div>
+ </UserButton.UserProfilePage>
+</UserButton>
diff --git a/integration/templates/astro-node/src/layouts/Layout.astro b/integration/templates/astro-node/src/layouts/Layout.astro
@@ -5,8 +5,9 @@ interface Props {
 
 const { title } = Astro.props;
 
-import { SignedIn, SignedOut, UserButton } from "@clerk/astro/components";
+import { SignedIn, SignedOut } from "@clerk/astro/components";
 import { LanguagePicker } from "../components/LanguagePicker";
+import CustomUserButton from "../components/CustomUserButton.astro";
 ---
 
 <!doctype html>
@@ -64,7 +65,7 @@ import { LanguagePicker } from "../components/LanguagePicker";
  <LanguagePicker client:idle />
 
  <SignedIn>
- <UserButton afterSignOutUrl="/" />
+ <CustomUserButton />
  </SignedIn>
 
  <SignedOut>

diff --git a/integration/tests/astro/components.test.ts b/integration/tests/astro/components.test.ts
@@ -57,7 +57,7 @@ testAgainstRunningApps({ withPattern: ['astro.node.withCustomRoles'] })('basic f
  await u.po.expect.toBeSignedIn();
  });
 
- test('render user button', async ({ page, context }) => {
+ test('renders user button', async ({ page, context }) => {
  const u = createTestUtils({ app, page, context });
  await u.page.goToRelative('/sign-in');
  await u.po.signIn.waitForMounted();
@@ -77,6 +77,72 @@ testAgainstRunningApps({ withPattern: ['astro.node.withCustomRoles'] })('basic f
  await expect(u.page.getByText(/profile details/i)).toBeVisible();
  });
 
+ test('renders user button with custom menu items', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ await u.page.goToRelative('/sign-in');
+ await u.po.signIn.waitForMounted();
+ await u.po.signIn.signInWithEmailAndInstantPassword({ email: fakeAdmin.email, password: fakeAdmin.password });
+ await u.page.waitForAppUrl('/');
+ await u.po.expect.toBeSignedIn();
+
+ await u.po.userButton.waitForMounted();
+ await u.po.userButton.toggleTrigger();
+ await u.po.userButton.waitForPopover();
+
+ // Check if custom menu items are visible
+ await u.po.userButton.toHaveVisibleMenuItems([/Custom link/i, /Custom action/i, /Custom click/i]);
+
+ // Click custom action and check for custom page availbility
+ await u.page.getByRole('menuitem', { name: /Custom action/i }).click();
+ await u.po.userProfile.waitForUserProfileModal();
+ await expect(u.page.getByRole('heading', { name: 'Custom Terms Page' })).toBeVisible();
+
+ // Close the modal and trigger the popover again
+ await u.page.locator('.cl-modalCloseButton').click();
+ await u.po.userButton.toggleTrigger();
+ await u.po.userButton.waitForPopover();
+
+ // Click custom action with click handler
+ const eventPromise = u.page.evaluate(() => {
+ return new Promise<string>(resolve => {
+ document.addEventListener(
+ 'clerk:menu-item-click',
+ (e: CustomEvent<string>) => {
+ resolve(e.detail);
+ },
+ { once: true },
+ );
+ });
+ });
+ await u.page.getByRole('menuitem', { name: /Custom click/i }).click();
+ expect(await eventPromise).toBe('custom_click');
+
+ // Trigger the popover again
+ await u.po.userButton.toggleTrigger();
+ await u.po.userButton.waitForPopover();
+
+ // Click custom link and check navigation
+ await u.page.getByRole('menuitem', { name: /Custom link/i }).click();
+ await u.page.waitForAppUrl('/user');
+ });
+
+ test('reorders default user button menu items and functions as expected', async ({ page, context }) => {
+ const u = createTestUtils({ app, page, context });
+ await u.page.goToRelative('/sign-in');
+ await u.po.signIn.waitForMounted();
+ await u.po.signIn.signInWithEmailAndInstantPassword({ email: fakeAdmin.email, password: fakeAdmin.password });
+ await u.page.waitForAppUrl('/');
+ await u.po.expect.toBeSignedIn();
+
+ await u.po.userButton.waitForMounted();
+ await u.po.userButton.toggleTrigger();
+ await u.po.userButton.waitForPopover();
+
+ // First item should now be the sign out button
+ await u.page.getByRole('menuitem').first().click();
+ await u.po.expect.toBeSignedOut();
+ });
+
  test('render user profile with streamed data', async ({ page, context }) => {
  const u = createTestUtils({ app, page, context });
  await u.page.goToRelative('/sign-in');

diff --git a/packages/astro/.eslintrc.cjs b/packages/astro/.eslintrc.cjs
@@ -4,7 +4,7 @@ module.exports = {
  rules: {
  'import/no-unresolved': ['error', { ignore: ['^#'] }],
  },
- ignorePatterns: ['src/astro-components/index.ts'],
+ ignorePatterns: ['src/astro-components/index.ts', 'src/astro-components/interactive/UserButton/index.ts'],
  overrides: [
  {
  files: ['./env.d.ts'],

diff --git a/packages/astro/src/astro-components/index.ts b/packages/astro/src/astro-components/index.ts
@@ -18,7 +18,7 @@ export { default as SignOutButton } from './unstyled/SignOutButton.astro';
  */
 export { default as SignIn } from './interactive/SignIn.astro';
 export { default as SignUp } from './interactive/SignUp.astro';
-export { default as UserButton } from './interactive/UserButton.astro';
+export { UserButton } from './interactive/UserButton';
 export { default as UserProfile } from './interactive/UserProfile.astro';
 export { default as OrganizationProfile } from './interactive/OrganizationProfile.astro';
 export { default as OrganizationSwitcher } from './interactive/OrganizationSwitcher.astro';

diff --git a/packages/astro/src/astro-components/interactive/InternalUIComponentRenderer.astro b/packages/astro/src/astro-components/interactive/InternalUIComponentRenderer.astro
@@ -1,14 +1,15 @@
 ---
 interface Props {
  [key: string]: unknown
+ id?: string
  component: 'sign-in' | 'sign-up' | 'organization-list' | 'organization-profile' | 'organization-switcher' | 'user-button' | 'user-profile' | 'google-one-tap'
 }
 
 import { generateSafeId } from '@clerk/astro/internal';
 
-const safeId = generateSafeId();
+const { component, id, ...props } = Astro.props
 
-const { component, ...props } = Astro.props
+const safeId = id || generateSafeId();
 ---
 
 <div data-clerk-id={`clerk-${component}-${safeId}`}></div>

diff --git a/packages/astro/src/astro-components/interactive/UserButton.astro b/packages/astro/src/astro-components/interactive/UserButton.astro
diff --git a/packages/astro/src/astro-components/interactive/UserButton/MenuItemRenderer.astro b/packages/astro/src/astro-components/interactive/UserButton/MenuItemRenderer.astro
@@ -0,0 +1,83 @@
+---
+type Props = {
+ label: string
+ href?: string
+ open?: string
+ clickIdentifier?: string
+ parent?: string
+}
+
+const { label, href, open, clickIdentifier, parent } = Astro.props
+
+let labelIcon = '';
+
+if (Astro.slots.has('label-icon')) {
+ labelIcon = await Astro.slots.render('label-icon');
+}
+
+const isDevMode = import.meta.env.DEV;
+---
+
+<script is:inline define:vars={{ label, href, open, clickIdentifier, labelIcon, isDevMode, parent }}>
+const parentElement = document.currentScript.parentElement;
+
+// We used a web component in the `<UserButton.MenuItems>` component.
+const hasParentMenuItem = parentElement.tagName.toLowerCase() === 'clerk-user-button-menu-items';
+if (!hasParentMenuItem) {
+ if (isDevMode) {
+ throw new Error(
+ `Clerk: <UserButton.MenuItems /> component can only accept <UserButton.Action /> and <UserButton.Link /> as its children. Any other provided component will be ignored.`
+ );
+ }
+ return
+}
+
+// Get the user button map from window that we set in the `<InternalUIComponentRenderer />`.
+const userButtonComponentMap = window.__astro_clerk_component_props.get('user-button');
+
+let userButton
+if (parent) {
+ userButton = document.querySelector(`[data-clerk-id="clerk-user-button-${parent}"]`);
+} else {
+ userButton = document.querySelector('[data-clerk-id^="clerk-user-button"]');
+}
+
+const safeId = userButton.getAttribute('data-clerk-id');
+const currentOptions = userButtonComponentMap.get(safeId);
+
+const reorderItemsLabels = ['manageAccount', 'signOut'];
+const isReorderItem = reorderItemsLabels.includes(label);
+
+let newMenuItem = {
+ label,
+}
+
+if (!isReorderItem) {
+ newMenuItem = {
+ ...newMenuItem,
+ mountIcon: (el) => {
+ el.innerHTML = labelIcon
+ },
+ unmountIcon: () => { /* What to clean up? */}
+ }
+
+ if (href) {
+ newMenuItem.href = href;
+ } else if (open) {
+ newMenuItem.open = open.startsWith('/') ? open : `/${open}`;
+ } else if (clickIdentifier) {
+ const clickEvent = new CustomEvent('clerk:menu-item-click', { detail: clickIdentifier });
+ newMenuItem.onClick = () => {
+ document.dispatchEvent(clickEvent);
+ }
+ }
+}
+
+userButtonComponentMap.set(safeId, {
+ ...currentOptions,
+ customMenuItems: [
+ ...(currentOptions?.customMenuItems ?? []),
+ newMenuItem,
+ ]
+})
+</script>
diff --git a/packages/astro/src/astro-components/interactive/UserButton/UserButton.astro b/packages/astro/src/astro-components/interactive/UserButton/UserButton.astro
@@ -0,0 +1,29 @@
+---
+import type { UserButtonProps, UserProfileProps, Without } from "@clerk/types";
+
+type Props = Without<UserButtonProps, 'userProfileProps'> & {
+ userProfileProps?: Pick<UserProfileProps, 'additionalOAuthScopes' | 'appearance'>;
+ /**
+ * If you have more than one UserButton on a page, providing a custom ID is required
+ * to properly scope menu items to the correct button.
+ *
+ * Example usage:
+ * ```tsx
+ * <UserButton id="someId">
+ * <UserButton.MenuItems>
+ * <UserButton.Link parent="someId" label="User" href="/user">
+ * <Icon slot="label-icon" />
+ * </UserButton.Link>
+ * </UserButton.MenuItems>
+ * </UserButton>
+ * ```
+ */
+ id?: string;
+}
+
+import InternalUIComponentRenderer from '../InternalUIComponentRenderer.astro'
+---
+
+<InternalUIComponentRenderer {...Astro.props} component="user-button" />
+
+<slot />
diff --git a/packages/astro/src/astro-components/interactive/UserButton/UserButtonAction.astro b/packages/astro/src/astro-components/interactive/UserButton/UserButtonAction.astro
@@ -0,0 +1,24 @@
+---
+import MenuItemRenderer from './MenuItemRenderer.astro';
+
+type ReorderItemsLabels = 'manageAccount' | 'signOut'
+
+type Props<Label extends string> = {
+ label: Label
+ parent?: string
+} & (Label extends ReorderItemsLabels
+ ? {
+ open?: string
+ }
+ : (
+ | { open: string; clickIdentifier?: string }
+ | { open?: string; clickIdentifier: string }
+ )
+)
+
+const { label, open, clickIdentifier, parent } = Astro.props
+---
+
+<MenuItemRenderer label={label} open={open} clickIdentifier={clickIdentifier} parent={parent}>
+ <slot name="label-icon" slot="label-icon" />
+</MenuItemRenderer>
diff --git a/packages/astro/src/astro-components/interactive/UserButton/UserButtonLink.astro b/packages/astro/src/astro-components/interactive/UserButton/UserButtonLink.astro
@@ -0,0 +1,15 @@
+---
+import MenuItemRenderer from './MenuItemRenderer.astro';
+
+interface Props {
+ label: string
+ href: string
+ parent?: string
+}
+
+const { label, href, parent } = Astro.props
+---
+
+<MenuItemRenderer label={label} href={href} parent={parent}>
+ <slot name="label-icon" slot="label-icon" />
+</MenuItemRenderer>
diff --git a/packages/astro/src/astro-components/interactive/UserButton/UserButtonMenuItems.astro b/packages/astro/src/astro-components/interactive/UserButton/UserButtonMenuItems.astro
@@ -0,0 +1,18 @@
+<clerk-user-button-menu-items>
+ <slot />
+</clerk-user-button-menu-items>
+
+<script>
+/**
+ * In the React version, menu items need to be wrapped in a `<UserButton.MenuItems>` component.
+ * We are trying to replicate that behavior here by adding a wrapper component
+ * and check if it exists inside the menu items components.
+ */
+class ClerkUserButtonMenuItems extends HTMLElement {
+ constructor() {
+ super();
+ }
+}
+
+customElements.define('clerk-user-button-menu-items', ClerkUserButtonMenuItems);
+</script>