diff --git a/docs/manifest.json b/docs/manifest.json index 8d4f85d4ab..1a30b04af5 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -3080,6 +3080,10 @@ "collapse": false, "items": [ [ + { + "title": "``", + "href": "/docs/reference/components/user/user-avatar" + }, { "title": "``", "href": "/docs/reference/components/user/user-button", diff --git a/docs/reference/components/overview.mdx b/docs/reference/components/overview.mdx index 09261cf3b7..1a0c53fa2a 100644 --- a/docs/reference/components/overview.mdx +++ b/docs/reference/components/overview.mdx @@ -13,6 +13,7 @@ Clerk offers a comprehensive suite of components designed to seamlessly integrat - [``](/docs/reference/components/authentication/google-one-tap) - [``](/docs/reference/components/user/user-button) - [``](/docs/reference/components/user/user-profile) +- [``](/docs/reference/components/user/user-avatar) - [``](/docs/reference/components/organization/create-organization) - [``](/docs/reference/components/organization/organization-profile) - [``](/docs/reference/components/organization/organization-switcher) diff --git a/docs/reference/components/user/user-avatar.mdx b/docs/reference/components/user/user-avatar.mdx new file mode 100644 index 0000000000..1398d118e2 --- /dev/null +++ b/docs/reference/components/user/user-avatar.mdx @@ -0,0 +1,384 @@ +--- +title: '`` component' +description: Clerk's component is used to render the familiar user avatar on its own. +search: + rank: 1 +sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue, js-frontend +--- + +![The \ component renders the authenticated user's avatar on its own, a common UI element found across many websites and applications.](/docs/images/ui-components/user-avatar.png) + +The `` component renders the authenticated user's avatar on its own, a common UI element found across many websites and applications. + + + ## Example + + In the following example, `` is mounted inside a header component, which is a common pattern on many websites and applications. When the user is signed in, they will see their avatar. + + + + ```tsx {{ filename: 'layout.tsx' }} + import { ClerkProvider, SignedIn, SignedOut, SignInButton, UserAvatar } from '@clerk/nextjs' + + function Header() { + return ( +
+

My App

+ + + + + + +
+ ) + } + + export default function RootLayout({ children }: { children: React.ReactNode }) { + return ( + + +
+ {children} + + + ) + } + ``` + + ```tsx {{ filename: 'pages/_app.tsx' }} + import { ClerkProvider, SignedIn, SignedOut, SignInButton, UserAvatar } from '@clerk/nextjs' + import type { AppProps } from 'next/app' + + function Header() { + return ( +
+

My App

+ + + + + + +
+ ) + } + + function MyApp({ pageProps, Component }: AppProps) { + return ( + +
+ + + ) + } + + export default MyApp + ``` + + + + + ```tsx {{ filename: 'src/App.tsx' }} + import { SignedIn, UserAvatar, SignInButton, SignedOut } from '@clerk/clerk-react' + + function App() { + return ( +
+ + + + + + +
+ ) + } + + export default App + ``` + + + + ```astro {{ filename: 'pages/index.astro' }} + --- + import { SignedIn, UserAvatar, SignInButton, SignedOut } from '@clerk/astro/components' + --- + + + + + + + + ``` + + + + + + ```jsx {{ filename: '/app/user-avatar.web.tsx' }} + import { SignedIn, UserAvatar, SignInButton, SignedOut } from '@clerk/clerk-expo/web' + + export default function Header() { + return ( +
+ + + + + + +
+ ) + } + ``` + + + + ```jsx {{ filename: 'src/layouts/root-layout.tsx' }} + import { SignedIn, UserAvatar, SignInButton, SignedOut } from '@clerk/chrome-extension' + + export default function Header() { + return ( +
+ + + + + + +
+ ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/_index.tsx' }} + import { SignedIn, UserAvatar, SignInButton, SignedOut } from '@clerk/remix' + + export default function Index() { + return ( +
+ + + + + + +
+ ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/home.tsx' }} + import { SignedIn, UserAvatar, SignInButton, SignedOut } from '@clerk/react-router' + + export default function Home() { + return ( +
+ + + + + + +
+ ) + } + ``` + + + + ```tsx {{ filename: 'app/routes/index.tsx' }} + import { SignedIn, UserAvatar, SignInButton, SignedOut } from '@clerk/tanstack-react-start' + import { createFileRoute } from '@tanstack/react-router' + + export const Route = createFileRoute('/')({ + component: Home, + }) + + function Home() { + return ( +
+ + + + + + +
+ ) + } + ``` + + + + ```vue {{ filename: 'components/AppHeader.vue' }} + + + + ``` + + + + ```vue {{ filename: 'header.vue' }} + + + + ``` + + + + + ## Usage with JavaScript + + The following methods available on an instance of the [`Clerk`](/docs/reference/javascript/clerk) class are used to render and control the `` component: + + - [`mountUserAvatar()`](#mount-user-avatar) + - [`unmountUserAvatar()`](#unmount-user-avatar) + + The following examples assume that you have followed the [quickstart](/docs/js-frontend/getting-started/quickstart) in order to add Clerk to your JavaScript application. + + ### `mountUserAvatar()` + + Render the `` component to an HTML `
` element. + + ```typescript + function mountUserAvatar(node: HTMLDivElement, props?: UserAvatarProps): void + ``` + + #### `mountUserAvatar()` params + + + - `node` + - [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement) + + The `
` element used to render in the `` component + + --- + + - `props?` + - [`UserAvatarProps`](#properties) + + The properties to pass to the `` component + + + #### `mountUserAvatar()` usage + + ```js {{ filename: 'main.js', mark: [15] }} + import { Clerk } from '@clerk/clerk-js' + + // Initialize Clerk with your Clerk Publishable Key + const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY + + const clerk = new Clerk(clerkPubKey) + await clerk.load() + + document.getElementById('app').innerHTML = ` +
+ ` + + const userAvatarDiv = document.getElementById('user-avatar') + + clerk.mountUserAvatar(userAvatarDiv) + ``` + + ### `unmountUserAvatar()` + + Unmount and run cleanup on an existing `` component instance. + + ```typescript + function unmountUserAvatar(node: HTMLDivElement): void + ``` + + #### `unmountUserAvatar()` params + + + - `node` + - [`HTMLDivElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement) + + The container `
` element with a rendered `` component instance. + + + #### `unmountUserAvatar()` usage + + ```js {{ filename: 'main.js', mark: [19] }} + import { Clerk } from '@clerk/clerk-js' + + // Initialize Clerk with your Clerk Publishable Key + const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY + + const clerk = new Clerk(clerkPubKey) + await clerk.load() + + document.getElementById('app').innerHTML = ` +
+ ` + + const userAvatarDiv = document.getElementById('user-avatar') + + clerk.mountUserAvatar(userAvatarDiv) + + // ... + + clerk.unmountUserAvatar(userAvatarDiv) + ``` + + +## Properties + +The `` component accepts the following properties, all of which are **optional**: + + + - `rounded?` + - `boolean` + + Determines whether the user avatar is displayed with rounded corners. + + --- + + - `appearance?` + - [Appearance](/docs/guides/customizing-clerk/appearance-prop/overview) | undefined + + Optional object to style your components. Will only affect [Clerk components](/docs/reference/components/overview) and not [Account Portal](/docs/guides/customizing-clerk/account-portal) pages. + + --- + + - `fallback?` + - `ReactNode` + + Optional element to be rendered while the component is mounting. + + +## Customization + +To learn about how to customize Clerk components, see the [customization documentation](/docs/guides/customizing-clerk/appearance-prop/overview). diff --git a/docs/reference/javascript/clerk.mdx b/docs/reference/javascript/clerk.mdx index 803a305b25..ff1edb58db 100644 --- a/docs/reference/javascript/clerk.mdx +++ b/docs/reference/javascript/clerk.mdx @@ -1190,6 +1190,11 @@ The `Clerk` class also contains a number of methods for interacting with prebuil - [`authenticateWithGoogleOneTap()`](/docs/reference/components/authentication/google-one-tap#authenticate-with-google-one-tap) - [`handleGoogleOneTapCallback()`](/docs/reference/components/authentication/google-one-tap#handle-google-one-tap-callback) +### `` + +- [`mountUserAvatar()`](/docs/reference/components/user/user-avatar#mount-user-avatar) +- [`unmountUserAvatar()`](/docs/reference/components/user/user-avatar#unmount-user-avatar) + ### `` - [`mountUserButton()`](/docs/reference/components/user/user-button#mount-user-button) diff --git a/public/images/ui-components/user-avatar.png b/public/images/ui-components/user-avatar.png new file mode 100644 index 0000000000..017969cf3d Binary files /dev/null and b/public/images/ui-components/user-avatar.png differ