<UserButton /> | OneAuxilia

<UserButton /> component

The <UserButton /> component is used to render the familiar user button UI popularized by Google.

OneAuxilia is the only provider with multi-session support, allowing users to sign into multiple accounts at once and switch between them. For multi-session apps, the <UserButton /> automatically supports instant account switching, without the need of a full page reload. For more information, you can check out the Multi-session applications guide.

Properties

All props are optional.

afterMultiSessionSingleSignOutUrl (deprecated) string

The full URL or path to navigate to after a signing out from a currently active account in a multi-session app. Deprecated - Move afterSignOutUrl to .

afterSignOutUrl (deprecated) string

The full URL or path to navigate to after a successful sign-out. Deprecated - Move afterSignOutUrl to .

afterSwitchSessionUrl string

The full URL or path to navigate to after a successful account change in a multi-session app.

appearance Appearance | undefined

Optional object to style your components. Will only affect OneAuxilia components and not Account Portal pages.

defaultOpen boolean

Controls whether the should open by default during the first render.

showName boolean

Controls if the user name is displayed next to the user image button

signInUrl string

The full URL or path to navigate to when the Add another account button is clicked. It's recommended to use the environment variable instead.

userProfileMode 'modal' | 'navigation'

Controls whether clicking the Manage your account button will cause the component to open as a modal, or if the browser will navigate to the userProfileUrl where is mounted as a page. Defaults to: 'modal'.

userProfileProps object

Specify options for the underlying component. For example: {additionalOAuthScopes: {google: ['foo', 'bar'], github: ['qux']}}.

userProfileUrl string

The full URL or path leading to the user management interface.

Usage with frameworks

In the following example, <UserButton /> 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 and be able to open the popup menu.ab

App Router

layout.tsx

import { OneAuxiliaProvider, SignedIn, SignedOut, SignInButton, UserButton } from '@oneauxilia/nextjs'

function Header() {
  return (
    <header style={{ display: 'flex', justifyContent: 'space-between', padding: 20 }}>
      <h1>My App</h1>
      <SignedIn>
        {/* Mount the UserButton component */}
        <UserButton />
      </SignedIn>
      <SignedOut>
        {/* Signed out users get sign in button */}
        <SignInButton />
      </SignedOut>
    </header>
  )
}

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <OneAuxiliaProvider>
        <Header />
        {children}
      </OneAuxiliaProvider>
    </html>
  )
}

Pages Router

userButtonExample.tsx

import { OneAuxiliaProvider, SignedIn, SignedOut, SignInButton, UserButton } from '@oneauxilia/nextjs'

function Header() {
  return (
    <header style={{ display: 'flex', justifyContent: 'space-between', padding: 20 }}>
      <h1>My App</h1>
      <SignedIn>
        {/* Mount the UserButton component */}
        <UserButton />
      </SignedIn>
      <SignedOut>
        {/* Signed out users get sign in button */}
        <SignInButton />
      </SignedOut>
    </header>
  )
}

function MyApp({ pageProps }) {
  return (
    <OneAuxiliaProvider {...pageProps}>
      <Header />
    </OneAuxiliaProvider>
  )
}

export default MyApp

app.tsx

import { OneAuxiliaProvider, SignedIn, SignIn, SignUp, UserButton } from '@oneauxilia/oneauxilia-react'
import { BrowserRouter, Route, Routes, useNavigate } from 'react-router-dom'

const oneauxilia_pub_key = process.env.REACT_APP_CLERK_PUBLISHABLE_KEY

function PublicPage() {
  return (
    <>
      <h1>Public page</h1>
      <a href="/protected">Go to protected page</a>
    </>
  )
}

function ProtectedPage() {
  return (
    <>
      <h1>Protected page</h1>
      <UserButton />
    </>
  )
}

function OneAuxiliaProviderWithRoutes() {
  const navigate = useNavigate()

  return (
    <OneAuxiliaProvider publishableKey={oneauxilia_pub_key} navigate={(to) => navigate(to)}>
      <Routes>
        <Route path="/" element={<PublicPage />} />
        <Route path="/sign-in/*" element={<SignIn routing="path" path="/sign-in" />} />
        <Route path="/sign-up/*" element={<SignUp routing="path" path="/sign-up" />} />
        <Route
          path="/protected"
          element={
            <SignedIn>
              <ProtectedPage />
            </SignedIn>
          }
        />
      </Routes>
    </OneAuxiliaProvider>
  )
}

function App() {
  return (
    <BrowserRouter>
      <OneAuxiliaProviderWithRoutes />
    </BrowserRouter>
  )
}

router/index.tsx

import { UserButton } from '@oneauxilia/remix'
import { getAuth } from '@oneauxilia/remix/ssr.server'
import { LoaderFunction, redirect } from '@remix-run/node'

export const loader: LoaderFunction = async (args) => {
  const { userId } = await getAuth(args)
  if (!userId) {
    return redirect('/sign-in')
  }
  return {}
}

export default function Index() {
  return (
    <div>
      <h1>Index route</h1>
      <p>You are signed in!</p>
      <UserButton />
    </div>
  )
}

pages/index.astro

---
import { SignedIn, UserButton } from '@oneauxilia/astro/components'
---

<SignedIn>
  <UserButton />
</SignedIn>

Usage with JavaScript

The following methods available on an instance of the OneAuxilia class are used to render and control the component:

mountUserButton()
unmountUserButton()

The following examples assume that you have followed the quickstart in order to add OneAuxilia to your JavaScript application.

mountUserButton()

Render the <UserButton /> component to an HTML <div> element.

function mountUserButton(node: HTMLDivElement, props?: UserButtonProps): void

mountUserButton() params

node HTMLDivElement

The <div> element used to render in the component

props? UserButtonProps

The properties to pass to the <UserButton /> component

mountUserButton() usage

main.js

import { OneAuxilia } from '@oneauxilia/oneauxilia-js'

// Initialize OneAuxilia with your OneAuxilia publishable key
const oneauxilia = new OneAuxilia('YOUR_PUBLISHABLE_KEY')
await oneauxilia.load()

document.getElementById('app').innerHTML = `
  <div id="user-button"></div>
`

const userbuttonDiv = document.getElementById('user-button')

oneauxilia.mountUserButton(userbuttonDiv)

index.html

<!-- Add a <div id="user-button"> element to your HTML -->
<div id="user-button"></div>

<!-- Initialize OneAuxilia with your
OneAuxilia Publishable key and Frontend API URL -->
<script
  async
  crossorigin="anonymous"
  data-oneauxilia-publishable-key="YOUR_PUBLISHABLE_KEY"
  src="https://YOUR_FRONTEND_API_URL/npm/@oneauxilia/oneauxilia-js@latest/dist/oneauxilia.browser.js"
  type="text/javascript"
></script>

<script>
  window.addEventListener('load', async function () {
    await OneAuxilia.load()

    const userbuttonDiv = document.getElementById('user-button')

    OneAuxilia.mountUserButton(userbuttonDiv)
  })
</script>

unmountUserButton()

Unmount and run cleanup on an existing <UserButton /> component instance.

function unmountUserButton(node: HTMLDivElement): void

unmountUserButton() params

node HTMLDivElement

The container <UserButton /> element with a rendered component instance.

unmountUserButton() usage

main.js

import { OneAuxilia } from '@oneauxilia/oneauxilia-js'

// Initialize OneAuxilia with your OneAuxilia publishable key
const oneauxilia = new OneAuxilia('YOUR_PUBLISHABLE_KEY')
await oneauxilia.load()

document.getElementById('app').innerHTML = `
  <div id="user-button"></div>
`

const userButtonDiv = document.getElementById('user-button')

oneauxilia.mountUserButton(userButtonDiv)

// ...

oneauxilia.unmountUserButton(userButtonDiv)

index.html

<!-- Add a <div id="user-button"> element to your HTML -->
<div id="user-button"></div>

<!-- Initialize OneAuxilia with your
OneAuxilia Publishable key and Frontend API URL -->
<script
  async
  crossorigin="anonymous"
  data-oneauxilia-publishable-key="YOUR_PUBLISHABLE_KEY"
  src="https://YOUR_FRONTEND_API_URL/npm/@oneauxilia/oneauxilia-js@latest/dist/oneauxilia.browser.js"
  type="text/javascript"
></script>

<script>
  window.addEventListener('load', async function () {
    await OneAuxilia.load()

    const userButtonDiv = document.getElementById('user-button')

    OneAuxilia.mountUserButton(userButtonDiv)

    // ...

    OneAuxilia.unmountUserButton(userButtonDiv)
  })
</script>

Customization

To learn about how to customize OneAuxilia components, see the customization documentation.

You can also add custom actions and links to the <UserButton /> menu.

PreviousUser Components Next<UserProfile />

Last updated 4 months ago

<UserButton /> component

The <UserButton /> component is used to render the familiar user button UI popularized by Google.

Properties

All props are optional.

afterMultiSessionSingleSignOutUrl (deprecated) string

The full URL or path to navigate to after a signing out from a currently active account in a multi-session app. Deprecated - Move afterSignOutUrl to .

afterSignOutUrl (deprecated) string

The full URL or path to navigate to after a successful sign-out. Deprecated - Move afterSignOutUrl to .

afterSwitchSessionUrl string

The full URL or path to navigate to after a successful account change in a multi-session app.

appearance Appearance | undefined

Optional object to style your components. Will only affect OneAuxilia components and not Account Portal pages.

defaultOpen boolean

Controls whether the should open by default during the first render.

showName boolean

Controls if the user name is displayed next to the user image button

signInUrl string

The full URL or path to navigate to when the Add another account button is clicked. It's recommended to use the environment variable instead.

userProfileMode 'modal' | 'navigation'

userProfileProps object

Specify options for the underlying component. For example: {additionalOAuthScopes: {google: ['foo', 'bar'], github: ['qux']}}.

userProfileUrl string

The full URL or path leading to the user management interface.

Usage with frameworks

App Router

layout.tsx

import { OneAuxiliaProvider, SignedIn, SignedOut, SignInButton, UserButton } from '@oneauxilia/nextjs'

function Header() {
  return (
    <header style={{ display: 'flex', justifyContent: 'space-between', padding: 20 }}>
      <h1>My App</h1>
      <SignedIn>
        {/* Mount the UserButton component */}
        <UserButton />
      </SignedIn>
      <SignedOut>
        {/* Signed out users get sign in button */}
        <SignInButton />
      </SignedOut>
    </header>
  )
}

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <OneAuxiliaProvider>
        <Header />
        {children}
      </OneAuxiliaProvider>
    </html>
  )
}

Pages Router

userButtonExample.tsx

import { OneAuxiliaProvider, SignedIn, SignedOut, SignInButton, UserButton } from '@oneauxilia/nextjs'

function Header() {
  return (
    <header style={{ display: 'flex', justifyContent: 'space-between', padding: 20 }}>
      <h1>My App</h1>
      <SignedIn>
        {/* Mount the UserButton component */}
        <UserButton />
      </SignedIn>
      <SignedOut>
        {/* Signed out users get sign in button */}
        <SignInButton />
      </SignedOut>
    </header>
  )
}

function MyApp({ pageProps }) {
  return (
    <OneAuxiliaProvider {...pageProps}>
      <Header />
    </OneAuxiliaProvider>
  )
}

export default MyApp

app.tsx

import { OneAuxiliaProvider, SignedIn, SignIn, SignUp, UserButton } from '@oneauxilia/oneauxilia-react'
import { BrowserRouter, Route, Routes, useNavigate } from 'react-router-dom'

const oneauxilia_pub_key = process.env.REACT_APP_CLERK_PUBLISHABLE_KEY

function PublicPage() {
  return (
    <>
      <h1>Public page</h1>
      <a href="/protected">Go to protected page</a>
    </>
  )
}

function ProtectedPage() {
  return (
    <>
      <h1>Protected page</h1>
      <UserButton />
    </>
  )
}

function OneAuxiliaProviderWithRoutes() {
  const navigate = useNavigate()

  return (
    <OneAuxiliaProvider publishableKey={oneauxilia_pub_key} navigate={(to) => navigate(to)}>
      <Routes>
        <Route path="/" element={<PublicPage />} />
        <Route path="/sign-in/*" element={<SignIn routing="path" path="/sign-in" />} />
        <Route path="/sign-up/*" element={<SignUp routing="path" path="/sign-up" />} />
        <Route
          path="/protected"
          element={
            <SignedIn>
              <ProtectedPage />
            </SignedIn>
          }
        />
      </Routes>
    </OneAuxiliaProvider>
  )
}

function App() {
  return (
    <BrowserRouter>
      <OneAuxiliaProviderWithRoutes />
    </BrowserRouter>
  )
}

router/index.tsx

import { UserButton } from '@oneauxilia/remix'
import { getAuth } from '@oneauxilia/remix/ssr.server'
import { LoaderFunction, redirect } from '@remix-run/node'

export const loader: LoaderFunction = async (args) => {
  const { userId } = await getAuth(args)
  if (!userId) {
    return redirect('/sign-in')
  }
  return {}
}

export default function Index() {
  return (
    <div>
      <h1>Index route</h1>
      <p>You are signed in!</p>
      <UserButton />
    </div>
  )
}

pages/index.astro

---
import { SignedIn, UserButton } from '@oneauxilia/astro/components'
---

<SignedIn>
  <UserButton />
</SignedIn>

Usage with JavaScript

The following methods available on an instance of the OneAuxilia class are used to render and control the component:

mountUserButton()
unmountUserButton()

The following examples assume that you have followed the quickstart in order to add OneAuxilia to your JavaScript application.

mountUserButton()

Render the <UserButton /> component to an HTML <div> element.

function mountUserButton(node: HTMLDivElement, props?: UserButtonProps): void

mountUserButton() params

node HTMLDivElement

The <div> element used to render in the component

props? UserButtonProps

The properties to pass to the <UserButton /> component

mountUserButton() usage

main.js

import { OneAuxilia } from '@oneauxilia/oneauxilia-js'

// Initialize OneAuxilia with your OneAuxilia publishable key
const oneauxilia = new OneAuxilia('YOUR_PUBLISHABLE_KEY')
await oneauxilia.load()

document.getElementById('app').innerHTML = `
  <div id="user-button"></div>
`

const userbuttonDiv = document.getElementById('user-button')

oneauxilia.mountUserButton(userbuttonDiv)

index.html

<!-- Add a <div id="user-button"> element to your HTML -->
<div id="user-button"></div>

<!-- Initialize OneAuxilia with your
OneAuxilia Publishable key and Frontend API URL -->
<script
  async
  crossorigin="anonymous"
  data-oneauxilia-publishable-key="YOUR_PUBLISHABLE_KEY"
  src="https://YOUR_FRONTEND_API_URL/npm/@oneauxilia/oneauxilia-js@latest/dist/oneauxilia.browser.js"
  type="text/javascript"
></script>

<script>
  window.addEventListener('load', async function () {
    await OneAuxilia.load()

    const userbuttonDiv = document.getElementById('user-button')

    OneAuxilia.mountUserButton(userbuttonDiv)
  })
</script>

unmountUserButton()

Unmount and run cleanup on an existing <UserButton /> component instance.

function unmountUserButton(node: HTMLDivElement): void

unmountUserButton() params

node HTMLDivElement

The container <UserButton /> element with a rendered component instance.

unmountUserButton() usage

main.js

import { OneAuxilia } from '@oneauxilia/oneauxilia-js'

// Initialize OneAuxilia with your OneAuxilia publishable key
const oneauxilia = new OneAuxilia('YOUR_PUBLISHABLE_KEY')
await oneauxilia.load()

document.getElementById('app').innerHTML = `
  <div id="user-button"></div>
`

const userButtonDiv = document.getElementById('user-button')

oneauxilia.mountUserButton(userButtonDiv)

// ...

oneauxilia.unmountUserButton(userButtonDiv)

index.html

<!-- Add a <div id="user-button"> element to your HTML -->
<div id="user-button"></div>

<!-- Initialize OneAuxilia with your
OneAuxilia Publishable key and Frontend API URL -->
<script
  async
  crossorigin="anonymous"
  data-oneauxilia-publishable-key="YOUR_PUBLISHABLE_KEY"
  src="https://YOUR_FRONTEND_API_URL/npm/@oneauxilia/oneauxilia-js@latest/dist/oneauxilia.browser.js"
  type="text/javascript"
></script>

<script>
  window.addEventListener('load', async function () {
    await OneAuxilia.load()

    const userButtonDiv = document.getElementById('user-button')

    OneAuxilia.mountUserButton(userButtonDiv)

    // ...

    OneAuxilia.unmountUserButton(userButtonDiv)
  })
</script>

Customization

To learn about how to customize OneAuxilia components, see the customization documentation.

You can also add custom actions and links to the <UserButton /> menu.

PreviousUser Components Next<UserProfile />

Last updated 4 months ago