diff --git a/docs/_partials/views/clerk-theme-colors-property.mdx b/docs/_partials/views/clerk-theme-colors-property.mdx new file mode 100644 index 0000000000..a54483887b --- /dev/null +++ b/docs/_partials/views/clerk-theme-colors-property.mdx @@ -0,0 +1,104 @@ + + - `primary` + - `Color` + + The primary color used throughout the views. + + --- + + - `background` + - `Color` + + The background color for containers. + + --- + + - `input` + - `Color` + + The background color used for input fields. + + --- + + - `danger` + - `Color` + + The color used for error states. + + --- + + - `success` + - `Color` + + The color used for success states. + + --- + + - `warning` + - `Color` + + The color used for warning states. + + --- + + - `foreground` + - `Color` + + The color used for text. + + --- + + - `mutedForeground` + - `Color` + + The color used for secondary text. + + --- + + - `primaryForeground` + - `Color` + + The color used for text on the primary background. + + --- + + - `inputForeground` + - `Color` + + The color used for text in input fields. + + --- + + - `neutral` + - `Color` + + The color that will be used to generate the neutral shades the views use. + + --- + + - `ring` + - `Color` + + The color of the ring when an interactive element is focused. + + --- + + - `muted` + - `Color` + + The color used for muted backgrounds. + + --- + + - `shadow` + - `Color` + + The base shadow color used in the views. + + --- + + - `border` + - `Color` + + The base border color used in the views. + diff --git a/docs/_partials/ios/customization.mdx b/docs/_partials/views/customization.mdx similarity index 70% rename from docs/_partials/ios/customization.mdx rename to docs/_partials/views/customization.mdx index 7587cd6d08..0e9d628cbe 100644 --- a/docs/_partials/ios/customization.mdx +++ b/docs/_partials/views/customization.mdx @@ -1,3 +1,3 @@ -To learn how to customize Clerk iOS views, see the [dedicated guide](/docs/guides/customizing-clerk/clerk-theme). +To learn how to customize Clerk views, see the [dedicated guide](/docs/guides/customizing-clerk/clerk-theme). If Clerk's prebuilt views don't meet your specific needs or if you require more control over the logic, you can rebuild the existing Clerk flows using the Clerk API. For more information, see the [custom flow guides](/docs/guides/development/custom-flows/overview). diff --git a/docs/guides/customizing-clerk/appearance-prop/captcha.mdx b/docs/guides/customizing-clerk/appearance-prop/captcha.mdx index 13577fae86..b5ccce750b 100644 --- a/docs/guides/customizing-clerk/appearance-prop/captcha.mdx +++ b/docs/guides/customizing-clerk/appearance-prop/captcha.mdx @@ -1,7 +1,7 @@ --- title: '`captcha` prop' description: Utilize Clerk's `captcha` prop in order to change the appearance of the CAPTCHA widget. -sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue, js-frontend, fastify, expressjs, js-backend, go, ruby, android +sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue, js-frontend, fastify, expressjs, js-backend, go, ruby --- {/* JS file: https://github.com/clerk/javascript/blob/main/packages/types/src/appearance.ts#L538 */} diff --git a/docs/guides/customizing-clerk/appearance-prop/layout.mdx b/docs/guides/customizing-clerk/appearance-prop/layout.mdx index 23d5573c8b..7069defacd 100644 --- a/docs/guides/customizing-clerk/appearance-prop/layout.mdx +++ b/docs/guides/customizing-clerk/appearance-prop/layout.mdx @@ -1,7 +1,7 @@ --- title: '`Layout` prop' description: Utilize Clerk's layout prop in order to change the layout of the and components, as well as set important links to your support, terms and privacy pages. -sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue, js-frontend, fastify, expressjs, js-backend, go, ruby, android +sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue, js-frontend, fastify, expressjs, js-backend, go, ruby --- {/* JS file: https://github.com/clerk/javascript/blob/main/packages/types/src/appearance.ts#L538 */} diff --git a/docs/guides/customizing-clerk/appearance-prop/overview.mdx b/docs/guides/customizing-clerk/appearance-prop/overview.mdx index 909748382f..b35c152569 100644 --- a/docs/guides/customizing-clerk/appearance-prop/overview.mdx +++ b/docs/guides/customizing-clerk/appearance-prop/overview.mdx @@ -1,7 +1,7 @@ --- title: '`Appearance` prop' description: Utilize Clerk's appearance property in order to share styles across every component or individually to any of the Clerk components. -sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue, js-frontend, fastify, expressjs, js-backend, go, ruby, android +sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue, js-frontend, fastify, expressjs, js-backend, go, ruby --- {/* JS file: https://github.com/clerk/javascript/blob/main/packages/types/src/appearance.ts#L619 */} diff --git a/docs/guides/customizing-clerk/appearance-prop/themes.mdx b/docs/guides/customizing-clerk/appearance-prop/themes.mdx index 06950307ac..b1b649710b 100644 --- a/docs/guides/customizing-clerk/appearance-prop/themes.mdx +++ b/docs/guides/customizing-clerk/appearance-prop/themes.mdx @@ -1,7 +1,7 @@ --- title: Themes description: Clerk currently offers six prebuilt themes for you to customize the overall appearance of your Clerk app. -sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue, js-frontend, fastify, expressjs, js-backend, go, ruby, android +sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue, js-frontend, fastify, expressjs, js-backend, go, ruby --- Clerk currently offers [six prebuilt themes](#available-themes) for you to customize the overall appearance of your Clerk application. diff --git a/docs/guides/customizing-clerk/appearance-prop/variables.mdx b/docs/guides/customizing-clerk/appearance-prop/variables.mdx index d01c543c3d..bb7ee00f60 100644 --- a/docs/guides/customizing-clerk/appearance-prop/variables.mdx +++ b/docs/guides/customizing-clerk/appearance-prop/variables.mdx @@ -1,7 +1,7 @@ --- title: '`Variables` prop' description: Utilize Clerk's variables property in order to adjust the general styles of the component's base theme, like colors, backgrounds, typography. -sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue, js-frontend, fastify, expressjs, js-backend, go, ruby, android +sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, tanstack-react-start, vue, js-frontend, fastify, expressjs, js-backend, go, ruby --- {/* JS file: https://github.com/clerk/javascript/blob/main/packages/types/src/appearance.ts#L399 */} diff --git a/docs/guides/customizing-clerk/clerk-theme.android.mdx b/docs/guides/customizing-clerk/clerk-theme.android.mdx new file mode 100644 index 0000000000..b2ef6821a3 --- /dev/null +++ b/docs/guides/customizing-clerk/clerk-theme.android.mdx @@ -0,0 +1,179 @@ +--- +title: '`ClerkTheme`' +description: Utilize Clerk's ClerkTheme to adjust the general styles of the Android views, like colors, fonts, and design properties. +sdk: android +--- + +The `ClerkTheme` is used to customize the appearance of Clerk Android views by adjusting colors, fonts, and design properties. It provides a comprehensive theming system that allows you to create a consistent visual experience across all Clerk views. + +## Structure + +`ClerkTheme` consists of five main properties: + +- **`colors`** - Color properties for various UI elements across light and dark modes. +- **`lightColors`** - Optional overrides that only apply when the system is in light mode. These will default to the `colors` property if not provided. +- **`darkColors`** - Optional overrides that only apply when the system is in dark mode. These will default to the `colors` property if not provided. +- **`typography`** - Font and typography properties for different text styles. +- **`design`** - Design properties like border radius. + +## Colors + +The `colors`,`lightColors`, and `darkColors` properties contain the following color options: + + + +## Fonts + +The `typography` property contains the following font options based on Android Dynamic Type: + + + - `displaySmall` + - `TextStyle` + + --- + + - `headlineLarge` + - `TextStyle` + + --- + + - `headlineMedium` + - `TextStyle` + + --- + + - `titleMedium` + - `TextStyle` + + --- + + - `titleSmall` + - `TextStyle` + + --- + + - `bodyLarge` + - `TextStyle` + + --- + + - `bodyMedium` + - `TextStyle` + + --- + + - `bodySmall` + - `TextStyle` + + --- + + - `labelMedium` + - `TextStyle` + + --- + + - `labelSmall` + - `TextStyle` + + +## Design + +The `design` property contains the following design options: + + + - `borderRadius` + - `Dp` + + The border radius used throughout the views. By default, this is set to `8.0`. + + +## Usage + +You can customize Clerk Android views by creating a `ClerkTheme` and applying it to Clerk's `customTheme` setter. + +### Apply a custom theme to all Clerk views + +To customize all Clerk views in your app, create a `ClerkTheme` and apply it where you initialize the Clerk SDK. + +```kotlin +import android.app.Application +import androidx.compose.ui.graphics.Color +import androidx.compose.ui.unit.dp +import com.clerk.api.Clerk +import com.clerk.api.ui.ClerkColors +import com.clerk.api.ui.ClerkDesign +import com.clerk.api.ui.ClerkTheme + +class WorkbenchApplication : Application() { + + override fun onCreate() { + super.onCreate() + val theme = ClerkTheme( + colors = ClerkColors(primary = Color.Black), + design = ClerkDesign(borderRadius = 24.dp), + typography = ClerkTypographyDefaults.displaySmall.copy(fontSize = 24.sp) + ) + + Clerk.initialize(this, "YOUR_PUBLIC_KEY", theme = theme) + } +} + +``` + +### Apply a theme to specific views + +You can apply a theme to specific Clerk views by passing a `ClerkTheme` to any Clerk UI component. The theme used here will apply to all children of this view. + +```kotlin +import androidx.compose.runtime.Composable +import androidx.compose.ui.Modifier +import androidx.compose.ui.graphics.Color +import androidx.compose.ui.unit.dp +import androidx.compose.ui.Alignment +import androidx.compose.foundation.layout.Box +import androidx.compose.foundation.layout.fillMaxSize +import androidx.compose.foundation.background +import com.clerk.api.Clerk +import com.clerk.api.ui.ClerkColors +import com.clerk.api.ui.ClerkDesign +import com.clerk.api.ui.ClerkTheme +import com.clerk.api.ui.ClerkTypographyDefaults +import com.clerk.api.ui.UserButton +import com.clerk.api.ui.AuthView + +@Composable +fun HomeScreen { + val user by Clerk.userFlow.collecAsStateWithLifecycle() + Box( + modifier = Modifier.fillMaxSize().background(color = Color(0xFFF9F9F9)), + contentAlignment = Alignment.Center, + ) { + if (user != null) { + UserButton() + } else { + AuthView(clerkTheme = ClerkTheme(colors = ClerkColors(primary = Color.Blue))) + } + } +} +``` + +### Custom fonts + +You can customize fonts by modifying the `typography` property of the `ClerkTheme`. + +#### Using a font family name + +```kotlin +AuthView(clerkTheme = ClerkTheme(typography = ClerkTypography(displaySmall = ClerkTypographyDefaults.displaySmall.copy(fontSize = 24.sp)))) +``` + +## Light and Dark mode support + +Clerk Android views automatically support both light and dark mode appearance, adapting seamlessly to the user's system preferences. + +
+ ![Light Mode](/docs/images/ui-components/android-user-profile-view.png){{ style: { maxWidth: '230px' } }} + ![Dark Mode](/docs/images/ui-components/android-user-profile-view-dark.png){{ style: { maxWidth: '230px' } }} +
+ +If Clerk's prebuilt theming doesn't meet your specific needs, you can create completely custom authentication flows using the Clerk API. For more information, see the [custom flow guides](/docs/guides/development/custom-flows/overview). diff --git a/docs/guides/customizing-clerk/clerk-theme.mdx b/docs/guides/customizing-clerk/clerk-theme.mdx index c3c0ef56b5..4d328c587e 100644 --- a/docs/guides/customizing-clerk/clerk-theme.mdx +++ b/docs/guides/customizing-clerk/clerk-theme.mdx @@ -18,110 +18,7 @@ The `ClerkTheme` is used to customize the appearance of Clerk iOS views by adjus The `colors` property contains the following color options: - - - `primary` - - `Color` - - The primary color used throughout the views. - - --- - - - `background` - - `Color` - - The background color for containers. - - --- - - - `input` - - `Color` - - The background color used for input fields. - - --- - - - `danger` - - `Color` - - The color used for error states. - - --- - - - `success` - - `Color` - - The color used for success states. - - --- - - - `warning` - - `Color` - - The color used for warning states. - - --- - - - `foreground` - - `Color` - - The color used for text. - - --- - - - `mutedForeground` - - `Color` - - The color used for secondary text. - - --- - - - `primaryForeground` - - `Color` - - The color used for text on the primary background. - - --- - - - `inputForeground` - - `Color` - - The color used for text in input fields. - - --- - - - `neutral` - - `Color` - - The color that will be used to generate the neutral shades the views use. - - --- - - - `ring` - - `Color` - - The color of the ring when an interactive element is focused. - - --- - - - `muted` - - `Color` - - The color used for muted backgrounds. - - --- - - - `shadow` - - `Color` - - The base shadow color used in the views. - - --- - - - `border` - - `Color` - - The base border color used in the views. - + ## Fonts @@ -296,7 +193,7 @@ struct CustomFontView: View { } ``` -## Light and Dark Mode Support +## Light and Dark mode support Clerk iOS views automatically support both light and dark mode appearance, adapting seamlessly to the user's system preferences. diff --git a/docs/index.mdx b/docs/index.mdx index e2d7177e11..81605cd8a8 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -7,7 +7,7 @@ template: wide Find all the guides and resources you need to develop with Clerk. - [Quickstarts & Tutorials](/docs/getting-started/quickstart/overview) @@ -34,7 +34,7 @@ Find all the guides and resources you need to develop with Clerk. - + - [Quickstarts & Tutorials](/docs/getting-started/quickstart/overview) - Explore our end-to-end tutorials and getting started guides for different application stacks using Clerk. diff --git a/docs/manifest.json b/docs/manifest.json index d7f54f00e5..624e6bc84e 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -415,8 +415,7 @@ "expressjs", "js-backend", "go", - "ruby", - "android" + "ruby" ], "items": [ [ @@ -446,7 +445,7 @@ }, { "title": "View customization", - "sdk": ["ios"], + "sdk": ["ios", "android"], "href": "/docs/guides/customizing-clerk/clerk-theme" }, { diff --git a/docs/reference/components/overview.mdx b/docs/reference/components/overview.mdx index 425c119129..aecf7dccb7 100644 --- a/docs/reference/components/overview.mdx +++ b/docs/reference/components/overview.mdx @@ -1,7 +1,7 @@ --- title: Component Reference description: A list of Clerk's comprehensive suite of components designed to seamlessly integrate authentication and multi-tenancy into your application. -sdk: react, nextjs, js-frontend, chrome-extension, expo, android, expressjs, fastify, react-router, remix, tanstack-react-start, go, astro, nuxt, vue, ruby, js-backend +sdk: react, nextjs, js-frontend, chrome-extension, expo, expressjs, fastify, react-router, remix, tanstack-react-start, go, astro, nuxt, vue, ruby, js-backend --- Clerk offers a comprehensive suite of components designed to seamlessly integrate authentication and multi-tenancy into your application. With Clerk components, you can easily customize the appearance of authentication components and pages, manage the entire authentication flow to suit your specific needs, and even build robust SaaS applications. diff --git a/docs/reference/views/authentication/auth-view.mdx b/docs/reference/views/authentication/auth-view.mdx index f0757d2ed1..09314c25c6 100644 --- a/docs/reference/views/authentication/auth-view.mdx +++ b/docs/reference/views/authentication/auth-view.mdx @@ -1,80 +1,125 @@ --- title: '`AuthView`' -description: Clerk's AuthView renders a UI for signing in and signing up users on iOS. -sdk: ios +description: Clerk's AuthView renders a UI for signing in and signing up users on your app. +sdk: ios, android --- -![The AuthView renders a comprehensive authentication interface that handles both user sign-in and sign-up flows.](/docs/images/ui-components/ios-auth-view.png){{ style: { maxWidth: '460px' } }} + + ![The AuthView renders a comprehensive authentication interface that handles both user sign-in and sign-up flows.](/docs/images/ui-components/ios-auth-view.png){{ style: { maxWidth: '460px' } }} + + + + ![The AuthView renders a comprehensive authentication interface that handles both user sign-in and sign-up flows.](/docs/images/ui-components/android-auth-view.png){{ style: { maxWidth: '460px' } }} + The `AuthView` renders a comprehensive authentication interface with support for multiple sign-up flows and sign-in methods, multi-factor authentication, password reset, and account recovery. The functionality of the `AuthView` is controlled by the instance settings you specify in the [Clerk Dashboard](https://dashboard.clerk.com), such as [sign-in and sign-up options](/docs/guides/configure/auth-strategies/sign-up-sign-in-options) and [social connections](/docs/guides/configure/auth-strategies/social-connections/all-providers). +By default, the `AuthView` will automatically determine whether to sign users in or sign them up based on whether they already have an account. This is the default mode that provides seamless authentication without requiring users to choose between sign-in and sign-up. + ## Parameters - - - `mode` - - `AuthView.Mode` + + + - `mode` + - `AuthView.Mode` + + The authentication mode that determines which flows are available to the user. Accepts the following values: + + - `.signInOrUp`: Automatically determines whether to sign users in or sign them up based on whether they already have an account. This is the default mode that provides seamless authentication without requiring users to choose between sign-in and sign-up. + - `.signIn`: Restricts the interface to sign-in flows only. Users can only authenticate with existing accounts. + - `.signUp`: Restricts the interface to sign-up flows only. Users can only create new accounts. + + Defaults to `.signInOrUp`. - The authentication mode that determines which flows are available to the user. Accepts the following values: + --- - - `.signInOrUp`: Automatically determines whether to sign users in or sign them up based on whether they already have an account. This is the default mode that provides seamless authentication without requiring users to choose between sign-in and sign-up. - - `.signIn`: Restricts the interface to sign-in flows only. Users can only authenticate with existing accounts. - - `.signUp`: Restricts the interface to sign-up flows only. Users can only create new accounts. + - `isDismissable` + - `Bool` - Defaults to `.signInOrUp`. + Whether the view can be dismissed by the user. When `true`, a dismiss button appears and the view closes automatically after successful authentication. When `false`, no dismiss button is shown. Defaults to `true`. + + - --- + + + - `modifier` - - `isDismissable` - - `Bool` + - `Modifier` - Whether the view can be dismissed by the user. When `true`, a dismiss button appears and the view closes automatically after successful authentication. When `false`, no dismiss button is shown. Defaults to `true`. - + A modifier that gets applied to the `AuthView` composable. This is by default applied to the top level `NavDisplay` and shouldn't be used to change the appearance of the `AuthView` itself. + + ## Usage -The following examples show how to use the `AuthView` in your iOS app. +The following examples show how to use the `AuthView` in your app. + + + ### Basic usage as a dismissable sheet + + ```swift + struct HomeView: View { + @Environment(\.clerk) private var clerk + @State private var authIsPresented = false + + var body: some View { + ZStack { + if clerk.user != nil { + UserButton() + .frame(width: 36, height: 36) + } else { + Button("Sign in") { + authIsPresented = true + } + } + } + .sheet(isPresented: $authIsPresented) { + AuthView() + } + } + } + ``` -### Basic usage as a dismissable sheet + ### Full-screen authentication (non-dismissable) -```swift -struct HomeView: View { - @Environment(\.clerk) private var clerk - @State private var authIsPresented = false + ```swift + struct ProfileView: View { + @Environment(\.clerk) private var clerk - var body: some View { - ZStack { + var body: some View { if clerk.user != nil { - UserButton() - .frame(width: 36, height: 36) + UserProfileView(isDismissable: false) } else { - Button("Sign in") { - authIsPresented = true - } + AuthView(isDismissable: false) } } - .sheet(isPresented: $authIsPresented) { - AuthView() - } } -} -``` + ``` + -### Full-screen authentication (non-dismissable) + + ### Basic usage -```swift -struct ProfileView: View { - @Environment(\.clerk) private var clerk + ```kotlin - var body: some View { - if clerk.user != nil { - UserProfileView(isDismissable: false) - } else { - AuthView(isDismissable: false) + import androidx.compose.runtime.Composable + import androidx.lifecycle.compose.collectAsStateWithLifecycle + import com.clerk.api.Clerk + + @Composable + fun HomeScreen { + val user by Clerk.userFlow.collecAsStateWithLifecycle() + Box(modifier = Modifier.fillMaxSize(), contentAlignment = Alignment.Center) { + if (user != null) { + UserButton() + } else { + AuthView() + } } } -} -``` + ``` + ## Customization - + diff --git a/docs/reference/views/overview.mdx b/docs/reference/views/overview.mdx index 5e21b4b229..5e3118e9b8 100644 --- a/docs/reference/views/overview.mdx +++ b/docs/reference/views/overview.mdx @@ -1,20 +1,42 @@ --- title: View Reference description: A list of Clerk's comprehensive suite of views designed to seamlessly integrate authentication and multi-tenancy into your application. -sdk: ios +sdk: ios, android --- Clerk offers a comprehensive suite of views designed to seamlessly integrate authentication and multi-tenancy into your application. With Clerk views, you can easily customize the appearance of authentication views and pages, manage the entire authentication flow to suit your specific needs, and even build robust SaaS applications. -## Clerk iOS views +## Clerk views - [`AuthView`](/docs/reference/views/authentication/auth-view) - Renders a full authentication interface, supporting multiple sign-up and sign-in methods, multi-factor authentication (MFA), and password recovery flows. - [`UserButton`](/docs/reference/views/user/user-button) - Displays the signed-in user's profile image. - [`UserProfileView`](/docs/reference/views/user/user-profile-view) - Renders a complete user profile interface with personal information, security settings, account switching, and sign-out options. + + ## Installation + + The Clerk Android SDK is now split into two packages: + + - `com.clerk:clerk-api` - The core Clerk SDK for authentication and user management. + - `com.clerk:clerk-ui` - The Clerk UI components for authentication and user management. + + The `com.clerk:clerk-ui` pulls the `com.clerk:clerk-api` package as a dependency, so you only need to add the `com.clerk:clerk-ui` package to your dependencies if you're using Clerk's UI components. + + ```gradle + dependencies { + // Only if you're using the Clerk API without the Clerk UI components + implementation("com.clerk:clerk-api:") + + implementation("com.clerk:clerk-ui:") + } + ``` + + You can find the latest version of the Clerk Android SDK on the [GitHub release page](https://github.com/clerk/clerk-android/releases). + + ## Customization - + ### Secured by Clerk branding diff --git a/docs/reference/views/user/user-button.mdx b/docs/reference/views/user/user-button.mdx index 8f99fce5e3..8a94ba9f12 100644 --- a/docs/reference/views/user/user-button.mdx +++ b/docs/reference/views/user/user-button.mdx @@ -1,61 +1,131 @@ --- title: '`UserButton`' description: Clerk's UserButton renders a circular button that displays the current user's profile image and opens the user profile when tapped. -sdk: ios +sdk: ios, android --- -![The UserButton is a circular button that displays the signed-in user's profile image.](/docs/images/ui-components/ios-user-button.png) + + ![The UserButton is a circular button that displays the signed-in user's profile image.](/docs/images/ui-components/ios-user-button.png) + + + + ![The UserButton is a circular button that displays the signed-in user's profile image.](/docs/images/ui-components/android-user-button.png) + The `UserButton` is a circular button that displays the signed-in user's profile image. When tapped, it presents a sheet with the [`UserProfileView`](/docs/reference/views/user/user-profile-view). > [!IMPORTANT] > The `UserButton` only appears when a user is signed in. + + ## Parameters + + + - `clerkTheme` + - `ClerkTheme` + + The theme to apply to the `UserButton`. This will override any theme applied to the `UserButton`'s parent view, or configured in the `Clerk` global object. + + + ## Usage -The following examples show how to use the `UserButton` in your iOS app. +The following examples show how to use the `UserButton` in your app. ### Basic usage -```swift -struct HomeView: View { - @Environment(\.clerk) private var clerk + + ```swift + struct HomeView: View { + @Environment(\.clerk) private var clerk - var body: some View { - ZStack { - if clerk.user != nil { - UserButton() - .frame(width: 36, height: 36) + var body: some View { + ZStack { + if clerk.user != nil { + UserButton() + .frame(width: 36, height: 36) + } } } } -} -``` + ``` + + + + ```kotlin + import androidx.compose.material3.ExperimentalMaterial3Api + import androidx.compose.material3.Text + import androidx.compose.material3.TopAppBar + import androidx.compose.runtime.Composable + import androidx.compose.runtime.getValue + import androidx.compose.ui.tooling.preview.PreviewLightDark + import androidx.lifecycle.compose.collectAsStateWithLifecycle + import com.clerk.api.Clerk + import com.clerk.ui.userbutton.UserButton + + @Composable + fun HomeScreen { + val user by Clerk.userFlow.collectAsStateWithLifecycle() + if (user != null) { + UserButton() + } + } + ``` + ### In a navigation toolbar -```swift -struct ContentView: View { - @Environment(\.clerk) private var clerk + + ```swift + struct ContentView: View { + @Environment(\.clerk) private var clerk - var body: some View { - NavigationView { - VStack { - Text("Welcome!") - } - .toolbar { - ToolbarItem(placement: .navigationBarTrailing) { - if clerk.user != nil { - UserButton() - .frame(width: 36, height: 36) + var body: some View { + NavigationView { + VStack { + Text("Welcome!") + } + .toolbar { + ToolbarItem(placement: .navigationBarTrailing) { + if clerk.user != nil { + UserButton() + .frame(width: 36, height: 36) + } } } } } } -} -``` + ``` + + + + ```kotlin + import androidx.compose.material3.ExperimentalMaterial3Api + import androidx.compose.material3.Scaffold + import androidx.compose.material3.Text + import androidx.compose.material3.TopAppBar + import androidx.compose.runtime.Composable + import androidx.compose.runtime.getValue + import androidx.compose.ui.tooling.preview.PreviewLightDark + import androidx.lifecycle.compose.collectAsStateWithLifecycle + import com.clerk.api.Clerk + import com.clerk.ui.userbutton.UserButton + + @Composable + fun UserProfileTopBar() { + val user by Clerk.userFlow.collectAsStateWithLifecycle() + Scaffold( + topBar = { + TopAppBar(title = { Text("Home screen") }, actions = { user?.let { UserButton() } }) + } + ) { + // Content goes here + } + } + ``` + ## Customization - + diff --git a/docs/reference/views/user/user-profile-view.mdx b/docs/reference/views/user/user-profile-view.mdx index 81af990dcc..7e13ae791a 100644 --- a/docs/reference/views/user/user-profile-view.mdx +++ b/docs/reference/views/user/user-profile-view.mdx @@ -1,10 +1,16 @@ --- title: '`UserProfileView`' description: Clerk's UserProfileView renders a beautiful, full-featured account management UI that allows users to manage their profile and security settings. -sdk: ios +sdk: ios, android --- -![The UserProfileView renders a comprehensive user profile interface that displays user information and provides account management options.](/docs/images/ui-components/ios-user-profile-view.png){{ style: { maxWidth: '460px' } }} + + ![The UserProfileView renders a comprehensive user profile interface that displays user information and provides account management options.](/docs/images/ui-components/ios-user-profile-view.png){{ style: { maxWidth: '460px' } }} + + + + ![The UserProfileView renders a comprehensive user profile interface that displays user information and provides account management options.](/docs/images/ui-components/android-user-profile-view.png){{ style: { maxWidth: '460px' } }} + The `UserProfileView` renders a comprehensive user profile interface that displays user information and provides account management options. It includes personal information, security settings, account switching, and sign-out functionality. @@ -13,57 +19,97 @@ The `UserProfileView` renders a comprehensive user profile interface that displa ## Parameters - - - `isDismissable` - - `Bool` + + + - `isDismissable` + - `Bool` + + Whether the view can be dismissed by the user. When `true`, a dismiss button appears in the navigation bar and the view can be used in sheets or other dismissable contexts. When `false`, no dismiss button is shown, making it suitable for full-screen usage. Defaults to `true`. + + + + + + - `clerkTheme` + - `ClerkTheme` + + The theme to apply to the `UserProfileView`. This will override any theme applied to the `UserProfileView`'s parent view, or configured in the `Clerk` global object. - Whether the view can be dismissed by the user. When `true`, a dismiss button appears in the navigation bar and the view can be used in sheets or other dismissable contexts. When `false`, no dismiss button is shown, making it suitable for full-screen usage. Defaults to `true`. - + --- + + - `onDismiss` + - `() -> Unit` + + A callback function that is called when the user dismisses the view, such as when they tap a back button or close button. Use this callback to handle navigation or perform cleanup when the user closes the profile view, for example, navigating back to the previous screen or updating your app's state. + + ## Usage -The following examples show how to use the `UserProfileView` in your iOS app. +The following examples show how to use the `UserProfileView` in your app. -### Dismissible sheet presentation + + ### Dismissible sheet presentation -Present `UserProfileView` as a dismissible sheet when you want users to be able to close the profile view and return to the previous screen. + Present `UserProfileView` as a dismissible sheet when you want users to be able to close the profile view and return to the previous screen. -```swift -struct MainView: View { - @Environment(\.clerk) private var clerk - @State private var profileIsPresented = false + ```swift + struct MainView: View { + @Environment(\.clerk) private var clerk + @State private var profileIsPresented = false - var body: some View { - VStack { - if clerk.user != nil { - Button("Show Profile") { - profileIsPresented = true + var body: some View { + VStack { + if clerk.user != nil { + Button("Show Profile") { + profileIsPresented = true + } } } - } - .sheet(isPresented: $profileIsPresented) { - UserProfileView() + .sheet(isPresented: $profileIsPresented) { + UserProfileView() + } } } -} -``` + ``` + ### Full-screen profile view Use `UserProfileView` as a full-screen view when you want to dedicate the entire screen to profile management. -```swift -struct ProfileView: View { - @Environment(\.clerk) private var clerk + + ```swift + struct ProfileView: View { + @Environment(\.clerk) private var clerk - var body: some View { - if clerk.user != nil { - UserProfileView(isDismissable: false) + var body: some View { + if clerk.user != nil { + UserProfileView(isDismissable: false) + } + } + } + ``` + + + + ```kotlin + import androidx.compose.runtime.Composable + import androidx.compose.runtime.getValue + import androidx.lifecycle.compose.collectAsStateWithLifecycle + import com.clerk.api.Clerk + import com.clerk.ui.userprofile.UserProfileView + + @Composable + fun ProfileView() { + val user by Clerk.userFlow.collectAsStateWithLifecycle() + if (user != null) { + UserProfileView() } } -} -``` + ``` + ## Customization - + diff --git a/public/images/ui-components/android-auth-view.png b/public/images/ui-components/android-auth-view.png new file mode 100644 index 0000000000..1deddbf023 Binary files /dev/null and b/public/images/ui-components/android-auth-view.png differ diff --git a/public/images/ui-components/android-user-button.png b/public/images/ui-components/android-user-button.png new file mode 100644 index 0000000000..efe6d62d3e Binary files /dev/null and b/public/images/ui-components/android-user-button.png differ diff --git a/public/images/ui-components/android-user-profile-view-dark.png b/public/images/ui-components/android-user-profile-view-dark.png new file mode 100644 index 0000000000..fea2c51f09 Binary files /dev/null and b/public/images/ui-components/android-user-profile-view-dark.png differ diff --git a/public/images/ui-components/android-user-profile-view.png b/public/images/ui-components/android-user-profile-view.png new file mode 100644 index 0000000000..0c959e330a Binary files /dev/null and b/public/images/ui-components/android-user-profile-view.png differ