Skip to main content

UserButton

The UserButton is a circular button that displays the signed-in user's profile image.

The UserButton is a circular button that displays the user's profile image. When tapped, it presents a sheet with the UserProfileView.

Important

When a user is signed out, the UserButton renders the signedOutContent you provide. If you don't provide any, it renders nothing.

  • Name
    signedOutContent
    Type
    @ViewBuilder () -> SignedOutContent
    Description

    A view builder that renders when no user is signed in. Defaults to EmptyView, which renders nothing.

Modifiers

Apply the following modifiers to a UserButton to customize the UserProfileView it presents.

  • Name
    userProfileDestination(_:)
    Type
    @ViewBuilder (Route) -> some View
    Description

    Builds the view to push when the user selects a custom row. The closure receives the selected row's route.

  • Name
    userProfileOAuthConfig(_:)
    Type
    [OAuthProviderConfig]
    Description

    Requests additional OAuth scopes or prompts per provider when the user connects or reconnects a social account. When an existing connected account hasn't approved every configured scope, UserProfileView offers to reconnect it. See Request additional OAuth scopes after sign-up for an example.

  • Name
    userProfileRows(_:)
    Type
    [UserProfileCustomRow<Route>]
    Description

    Custom rows to show on the root profile screen, alongside Clerk's built-in rows. Rows that share a placement show in array order.

  • Name
    icon
    Type
    UserProfileRowIcon
    Description

    The row's icon. Pass .system(name:) for an SF Symbol, or .asset(name:width:height:) for an image in your app's asset catalog. Clerk renders asset icons as templates, tinted the same color as its built-in row icons, and sizes them 24 × 24 points by default.

  • Name
    placement
    Type
    UserProfileCustomRowPlacement
    Description

    Where to insert the row relative to Clerk's built-in rows:

    • .sectionStart(_:) or .sectionEnd(_:): The start or end of the .profile or .account section
    • .before(_:) or .after(_:): Before or after a built-in row (.manageAccount, .security, .switchAccount, .addAccount, or .signOut)

    Defaults to .sectionEnd(.profile).

    A row placed before or after a built-in row appears only when that built-in row does. .switchAccount and .addAccount appear only in multi-session applications, and .switchAccount only when the user has more than one session. To always show a row in the account section, use .sectionStart(.account) or .sectionEnd(.account).

  • Name
    route
    Type
    Route: Hashable
    Description

    The value passed to userProfileDestination(_:), or pushed onto your navigationPath, when the user selects the row.

  • Name
    title
    Type
    LocalizedStringKey | String
    Description

    The row's title.

  • Name
    additionalScopes
    Type
    [String]
    Description

    Additional OAuth scopes to request from the provider. Defaults to [].

  • Name
    prompts
    Type
    [OIDCPrompt]
    Description

    OpenID Connect prompts to send to the provider: .none, .login, .consent, or .selectAccount. Defaults to [].

  • Name
    provider
    Type
    OAuthProvider
    Description

    The provider the configuration applies to, such as .google.

Usage

The following examples show how to use the UserButton in your app.

Basic usage

import SwiftUI
import ClerkKit
import ClerkKitUI

struct HomeView: View {
  @State private var authViewIsPresented = false

  var body: some View {
    VStack {
      UserButton(signedOutContent: {
        Button("Sign in") {
          authViewIsPresented = true
        }
      })
    }
    .prefetchClerkImages()
    .sheet(isPresented: $authViewIsPresented) {
      AuthView()
    }
  }
}
import SwiftUI
import ClerkKit
import ClerkKitUI

struct ContentView: View {
  @State private var authViewIsPresented = false

  var body: some View {
    NavigationView {
      VStack {
        Text("Welcome!")
      }
      .toolbar {
        ToolbarItem(placement: .navigationBarTrailing) {
          UserButton(signedOutContent: {
            Button("Sign in") {
              authViewIsPresented = true
            }
          })
        }
      }
    }
    .prefetchClerkImages()
    .sheet(isPresented: $authViewIsPresented) {
      AuthView()
    }
  }
}

Add custom rows to the presented profile

The following example adds a Billing row to the profile that UserButton presents.

import SwiftUI
import ClerkKit
import ClerkKitUI

enum ProfileRoute: Hashable {
  case billing
}

struct HomeView: View {
  var body: some View {
    UserButton()
      .userProfileRows([
        .init(route: ProfileRoute.billing, title: "Billing", icon: .system(name: "creditcard"), placement: .after(.security)),
      ])
      .userProfileDestination { (route: ProfileRoute) in
        switch route {
        case .billing:
          // Replace this placeholder with the custom view for your Billing row.
          Text("Billing")
        }
      }
  }
}

Customization

To learn how to customize Clerk views, see the dedicated guide.

Note

Clerk iOS views automatically localize based on the current SwiftUI locale and the device's preferred language. To see the languages Clerk iOS currently supports, check the SDK's Localizable.xcstrings file. The list of supported languages expands as Clerk adds new translations.

If you want to test localization in SwiftUI, you can force a locale on the view. For example:

AuthView()
  .environment(\.locale, .init(identifier: "es"))

For more about working with locales in SwiftUI, see Apple's locale environment value documentation.

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.

Feedback

What did you think of this content?

Last updated on