Skip to main content

useHostedAuth()

The useHostedAuth() hook opens Clerk's Account Portal in a browser authentication session and activates the session created there. Use it to add hosted sign-in and sign-up to a native Expo app.

Installation

This hook requires the following peer dependencies:

terminal
npx expo install expo-auth-session expo-crypto expo-web-browser

Then, import the hook from the @clerk/expo/hosted-auth subpath:

import { useHostedAuth } from '@clerk/expo/hosted-auth'

Returns

The useHostedAuth() hook returns the startHostedAuth() method.

startHostedAuth()

startHostedAuth() has the following function signature:

function startHostedAuth(params?: StartHostedAuthParams): Promise<StartHostedAuthReturnType>

Parameters

startHostedAuth() accepts the following parameters (StartHostedAuthParams):

  • Name
    mode?
    Type
    'sign-in' | 'sign-up'
    Description

    The Account Portal page to open first. Defaults to 'sign-in'.

  • Name
    redirectUrl?
    Type
    string
    Description

    The native callback URL. By default, Clerk creates a callback from the configured iOS bundle identifier or Android package name. Custom values must use a non-HTTP URL scheme and, in production, match a callback registered for the app on the Clerk Dashboard's Native applications page.

  • Name
    authSessionOptions?
    Type
    Pick<WebBrowser.AuthSessionOpenOptions, 'showInRecents' | 'preferEphemeralSession'>
    Description

    Options passed to expo-web-browser when Clerk opens the authentication session.

Returns

startHostedAuth() returns the following values after the browser session closes:

  • Name
    createdSessionId
    Type
    string | null
    Description

    The ID of the session that Clerk activated, or null if authentication didn't complete.

  • Name
    authSessionResult
    Type
    WebBrowser.WebBrowserAuthSessionResult | null
    Description

    The result from expo-web-browser, or null if Clerk wasn't loaded when the method ran.

Example

The following example opens Account Portal:

import { useHostedAuth } from '@clerk/expo/hosted-auth'
import { Button } from 'react-native'

export function SignInButton() {
  const { startHostedAuth } = useHostedAuth()

  const handleSignIn = async () => {
    try {
      await startHostedAuth()
    } catch (error) {
      // Handle the error in your app.
    }
  }

  return <Button title="Sign in" onPress={handleSignIn} />
}

For setup instructions, sign-up mode, platform callbacks, and tradeoffs, see the hosted authentication guide.

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub