Skip to content

feat(mosaic): add settings search to UserProfile and OrganizationProfile - #10492

Open
alexcarpenter wants to merge 4 commits into
mainfrom
carp/mosaic-profile-search-2
Open

alexcarpenter wants to merge 4 commits into
mainfrom
carp/mosaic-profile-search-2

Conversation

@alexcarpenter

@alexcarpenter alexcarpenter commented Oct 28, 2026 •

Copy link
Copy Markdown
Member

Description

Adds settings search to the Mosaic UserProfile and OrganizationProfile. It builds on #10196 and adds a way for custom pages to put their own content into the search.

  • Turning it on: search is off by default. Pass showSearch to UserProfile or OrganizationProfile to show it.
  • What it finds: a search field above the column navigation finds pages by their label or keywords, and sections on any page, including pages that aren't open. Results are grouped by page.
  • Choosing a result: it opens the page, scrolls the section into view if it isn't already (instantly when reduced motion is on), focuses it and briefly highlights it.
  • Built-in sections opt in with Section.Root search={{ label, keywords }}, which adds no extra DOM.
  • Custom pages use UserProfile.SearchTarget / OrganizationProfile.SearchTarget. Pass your own element as render to make it the target, with no wrapper. Custom pages also accept keywords.
  • useIsSearchIndexing() is exported so a page can skip work that only the visible page needs.
<UserProfile
  showSearch
  customPages={[
    {
      path: 'usage',
      label: 'Usage',
      keywords: ['plan'],
      content: (
        <UserProfile.SearchTarget label='Quota' keywords={['limits']} render={<section />}>
          <h3>Quota</h3>
        </UserProfile.SearchTarget>
      ),
    },
  ]}
/>

How the index is built: while the search field is focused or has a query, the profile renders every page a second time into a detached container. Each target renders an empty marker there instead of its children, and a MutationObserver turns the markers into the index. The index is always what each page actually renders, so permission checks, loading states and custom pages need nothing extra. A page that throws while it's indexed is left out, and the other pages stay searchable.

The highlight is one element the profile renders behind the page content. It is placed over the target with CSS anchor positioning, so the target itself gets no position or isolation, only anchor-name while it's highlighted. It uses the same support check as the tabs indicator, and where that fails the highlight doesn't show; the scroll and focus still happen.

A profile page that is leaving is now taken out of the layout (position: absolute) until its exit ends, so it no longer pushes the new page down. Without this, a result on another page was scrolled to where it sat below the old page.

The search is only shown in the column layout. It is hidden in the select and sheet layouts.

The swingset live UserProfile and OrganizationProfile pages turn on showSearch, and the UserProfile page adds a Usage custom page that uses UserProfile.SearchTarget.

Checklist

  • pnpm test runs as expected.
  • pnpm build runs as expected.
  • (If applicable) JSDoc comments have been added or updated for any package exports
  • (If applicable) Documentation has been updated

Type of change

  • 🐛 Bug fix
  • 🌟 New feature
  • 🔨 Breaking change
  • 📖 Refactoring / dependency upgrade / documentation
  • other:

@vercel

vercel Bot commented Oct 28, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
clerk-js-sandbox Ready Ready Preview Oct 28, 2026 10:05pm UTC
swingset Ready Ready Preview Oct 28, 2026 10:05pm UTC

Request Review

@changeset-bot

changeset-bot Bot commented Oct 28, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 99e30f7

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@coderabbitai

coderabbitai Bot commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

No actionable comments were generated in the recent review.

Recent review info
Run configuration
Commits

Reviewing files that changed from the base of the PR and between 615bc7c and 99e30f7.

Files selected for processing: 39
  • .changeset/mosaic-profile-search.md
  • packages/mosaic/src/components/profile/index.ts
  • packages/mosaic/src/components/profile/profile-search-index.tsx
  • packages/mosaic/src/components/profile/profile-search.styles.ts
  • packages/mosaic/src/components/profile/profile-search.test.tsx
  • packages/mosaic/src/components/profile/profile-search.tsx
  • packages/mosaic/src/components/profile/profile.context.ts
  • packages/mosaic/src/components/profile/profile.messages.ts
  • packages/mosaic/src/components/profile/profile.styles.ts
  • packages/mosaic/src/components/profile/profile.tsx
  • packages/mosaic/src/components/section/section.tsx
  • packages/mosaic/src/features/organization-profile/__tests__/organization-profile.feature.test.tsx
  • packages/mosaic/src/features/organization-profile/__tests__/organization-profile.view.test.tsx
  • packages/mosaic/src/features/organization-profile/organization-profile-danger-section/organization-profile-danger-section.view.tsx
  • packages/mosaic/src/features/organization-profile/organization-profile-profile-section/organization-profile-profile-section.view.tsx
  • packages/mosaic/src/features/organization-profile/organization-profile.tsx
  • packages/mosaic/src/features/organization-profile/organization-profile.types.ts
  • packages/mosaic/src/features/organization-profile/organization-profile.view.tsx
  • packages/mosaic/src/features/user-profile/__tests__/user-profile.feature.test.tsx
  • packages/mosaic/src/features/user-profile/__tests__/user-profile.view.test.tsx
  • packages/mosaic/src/features/user-profile/user-profile-active-devices-section/user-profile-active-devices-section.view.tsx
  • packages/mosaic/src/features/user-profile/user-profile-billing-history-section/user-profile-billing-history-section.view.tsx
  • packages/mosaic/src/features/user-profile/user-profile-connected-accounts-section/user-profile-connected-accounts-section.view.tsx
  • packages/mosaic/src/features/user-profile/user-profile-danger-section/user-profile-danger-section.view.tsx
  • packages/mosaic/src/features/user-profile/user-profile-email-section/user-profile-email-section.view.tsx
  • packages/mosaic/src/features/user-profile/user-profile-enterprise-accounts-section/user-profile-enterprise-accounts-section.view.tsx
  • packages/mosaic/src/features/user-profile/user-profile-passkeys-section/user-profile-passkeys-section.view.tsx
  • packages/mosaic/src/features/user-profile/user-profile-password-section/user-profile-password-section.view.tsx
  • packages/mosaic/src/features/user-profile/user-profile-payment-methods-section/user-profile-payment-methods-section.view.tsx
  • packages/mosaic/src/features/user-profile/user-profile-phone-section/user-profile-phone-section.view.tsx
  • packages/mosaic/src/features/user-profile/user-profile-profile-section/user-profile-profile-section.view.tsx
  • packages/mosaic/src/features/user-profile/user-profile-security-list.tsx
  • packages/mosaic/src/features/user-profile/user-profile-subscription-section/user-profile-subscription-section.view.tsx
  • packages/mosaic/src/features/user-profile/user-profile-web3-wallets-section/user-profile-web3-wallets-section.view.tsx
  • packages/mosaic/src/features/user-profile/user-profile.tsx
  • packages/mosaic/src/features/user-profile/user-profile.types.ts
  • packages/mosaic/src/features/user-profile/user-profile.view.tsx
  • packages/swingset/src/app/(clerk)/live/organization-profile/organization-profile/page.tsx
  • packages/swingset/src/app/(clerk)/live/user-profile/user-profile/page.tsx
Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

Included review availability: This review used your included allowance. 3 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 4 reviews per hour.

Walkthrough

The change adds searchable pages and sections to the profile components. Search can match page labels, page keywords, and indexed target labels or keywords. Selecting a result navigates to its page and target. User and organization profiles gain an opt-in search setting, and custom pages can define keywords. The change also adds search labels to profile sections, tests, and live profile examples.

Priority: Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

  • clerk/javascript#10491: Refactors Profile.Nav, Profile.Content, and Profile.ContentPanel, which this change also extends.

Suggested reviewers: austincalvelage, maxyinger

Merge Risk: Minimal · up to 99e30

No actionable merge-blocking risk remains from the reviewed changes; the empty changeset is acceptable for this internally exposed feature.

Pre-merge checks: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Docstring Coverage Warning Docstring coverage is 5.41% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat… Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 4 passed
Check name Status Explanation
Title check Passed The title clearly and concisely describes the main change: adding settings search to Mosaic UserProfile and OrganizationProfile.
Description check Passed The description directly explains the new profile search feature, its behavior, configuration, supported targets, tests, and affected live pages.
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Docstring Coverage

Explanation

Docstring coverage is 5.41% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 37 functions across 38 files. (1 skipped: 1 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Linked repositories: Some configured repositories could not be included in this review. Cross-repository analysis may be incomplete. Please check linked-repository access and settings.

Comment @coderabbitai help to get the list of available commands.

@pkg-pr-new

pkg-pr-new Bot commented Oct 28, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@10492

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@10492

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@10492

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@10492

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@10492

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@10492

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@10492

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@10492

@clerk/expo-biometrics

npm i https://pkg.pr.new/@clerk/expo-biometrics@10492

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@10492

@clerk/expo-native-components

npm i https://pkg.pr.new/@clerk/expo-native-components@10492

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@10492

@clerk/express

npm i https://pkg.pr.new/@clerk/express@10492

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@10492

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@10492

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@10492

@clerk/mosaic

npm i https://pkg.pr.new/@clerk/mosaic@10492

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@10492

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@10492

@clerk/react

npm i https://pkg.pr.new/@clerk/react@10492

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@10492

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@10492

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@10492

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@10492

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@10492

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@10492

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@10492

commit: 99e30f7

A leaving profile page is taken out of the layout so it no longer pushes the
new page down while it exits, and a found target scrolls only as far as it
needs to be in view.
Search is now off by default. Pass showSearch to show it.

This branch was successfully deployed

2 active deployments
Preview – swingset — 99e30f7f Deployed Oct 28, 2026 by vercel[bot]
Preview – clerk-js-sandbox — 99e30f7f Deployed Oct 28, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant