|
| 1 | +# MosaicProvider |
| 2 | + |
| 3 | +`MosaicProvider` holds the settings shared by the Mosaic components below it: reading direction, icons, |
| 4 | +localization, experimental features and the profile. It also renders the toasts and profile modals those |
| 5 | +components open. |
| 6 | + |
| 7 | +## Usage |
| 8 | + |
| 9 | +Wrap the part of your app that uses Mosaic. Every prop is optional. |
| 10 | + |
| 11 | +```tsx |
| 12 | +import { MosaicProvider } from '@clerk/mosaic'; |
| 13 | + |
| 14 | +<MosaicProvider> |
| 15 | + <UserButton /> |
| 16 | +</MosaicProvider>; |
| 17 | +``` |
| 18 | + |
| 19 | +## Props |
| 20 | + |
| 21 | +| Prop | Type | Default | Description | |
| 22 | +| -------------- | --------------------- | ------- | ----------------------------------------------------------------------------- | |
| 23 | +| `children` | `ReactNode` | — | The components that use these settings. | |
| 24 | +| `direction` | `'ltr' \| 'rtl'` | `'ltr'` | The direction arrow-key navigation follows. Set it to match the page's `dir`. | |
| 25 | +| `icons` | `MosaicIconOverrides` | — | Glyph overrides by name. See [Icon](/components/icon). | |
| 26 | +| `localization` | `MosaicLocalization` | — | Locale and strings. See [Localization](/localization/localization). | |
| 27 | +| `experimental` | `MosaicExperimental` | — | Features still being tried out. Names and behavior can change in any release. | |
| 28 | +| `profile` | `MosaicProfile` | — | The profile shared by the profile components, described below. | |
| 29 | + |
| 30 | +## Experimental |
| 31 | + |
| 32 | +| Option | Type | Default | Description | |
| 33 | +| ------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- | |
| 34 | +| `newProfiles` | `boolean` | `false` | `UserButton` and `OrganizationSwitcher` open Mosaic's own `UserProfile` and `OrganizationProfile` instead of Clerk's modals. | |
| 35 | + |
| 36 | +## Profile |
| 37 | + |
| 38 | +`profile` configures the profile that `UserButton`, `OrganizationSwitcher`, `UserProfile` and |
| 39 | +`OrganizationProfile` share. `UserProfile` and `OrganizationProfile` use it for any prop they don't set |
| 40 | +themselves. |
| 41 | + |
| 42 | +```tsx |
| 43 | +<MosaicProvider |
| 44 | + profile={{ |
| 45 | + combined: true, |
| 46 | + userProfileUrl: '/account', |
| 47 | + userProfileProps: { customPages }, |
| 48 | + organizationProfileProps: { pageOrder, afterLeaveOrganizationUrl: '/' }, |
| 49 | + }} |
| 50 | +> |
| 51 | + <OrganizationSwitcher /> |
| 52 | + <UserButton combined={false} /> |
| 53 | +</MosaicProvider> |
| 54 | +``` |
| 55 | + |
| 56 | +`combined` on `MosaicProvider` decides what the profile shows, and `combined` on `UserButton` decides what |
| 57 | +its menu lists. [Profile permutations](/user-button/profile-permutations) shows each pairing. |
| 58 | + |
| 59 | +| Option | Type | Default | Description | |
| 60 | +| -------------------------- | -------------------------- | ------- | --------------------------------------------------------------------------------- | |
| 61 | +| `combined` | `boolean` | `true` | Whether one profile carries the account's pages and the active organization's. | |
| 62 | +| `userProfileUrl` | `string` | — | Your own user profile page. Setting it routes there instead of opening the modal. | |
| 63 | +| `userProfileMode` | `'modal' \| 'navigation'` | — | How the user profile opens. Follows from whether `userProfileUrl` is set. | |
| 64 | +| `organizationProfileUrl` | `string` | — | Your own organization profile page. Setting it routes there instead of the modal. | |
| 65 | +| `organizationProfileMode` | `'modal' \| 'navigation'` | — | How the organization profile opens. Follows from `organizationProfileUrl`. | |
| 66 | +| `userProfileProps` | `ProfileUserProps` | — | Options for the user profile. | |
| 67 | +| `organizationProfileProps` | `ProfileOrganizationProps` | — | Options for the organization profile, or its pages in a combined profile. | |
| 68 | + |
| 69 | +### `userProfileProps` |
| 70 | + |
| 71 | +| Option | Type | Default | Description | |
| 72 | +| ----------------------- | ----------------------- | ------- | ------------------------------------------------------------ | |
| 73 | +| `customPages` | `CustomProfilePage[]` | — | Your own pages inside the profile. | |
| 74 | +| `pageOrder` | `string[]` | — | Navigation order, by built-in page id or custom page `path`. | |
| 75 | +| `additionalOAuthScopes` | `AdditionalOAuthScopes` | — | Extra access to request from each OAuth provider. | |
| 76 | +| `apiKeysProps` | `APIKeysPageProps` | — | Options for the API keys page. | |
| 77 | + |
| 78 | +### `organizationProfileProps` |
| 79 | + |
| 80 | +| Option | Type | Default | Description | |
| 81 | +| --------------------------- | --------------------- | ------- | ------------------------------------------------------------ | |
| 82 | +| `customPages` | `CustomProfilePage[]` | — | Your own pages inside the profile. | |
| 83 | +| `pageOrder` | `string[]` | — | Navigation order, by built-in page id or custom page `path`. | |
| 84 | +| `afterLeaveOrganizationUrl` | `string` | — | Where the user lands after leaving the organization. | |
| 85 | +| `apiKeysProps` | `APIKeysPageProps` | — | Options for the API keys page. | |
0 commit comments