Skip to main content
The YouVersionAuthButton component provides a pre-styled button for signing in and out with YouVersion OAuth. It automatically handles authentication flow and displays appropriate content based on auth state.

​
Basic Usage

import { YouVersionAuthButton } from '@youversion/platform-react-ui';

function MyComponent() {
  return (
    <YouVersionAuthButton
      onAuthError={(error) => console.error(error)}
    />
  );
}

​
Props

​
background
'light' | 'dark'
Theme for the button.Default: Inherits from provider
​
mode
'signIn' | 'signOut' | 'auto'
Button behavior:
  • 'signIn': Always shows sign in
  • 'signOut': Always shows sign out
  • 'auto': Shows sign in when not authenticated, sign out when authenticated
Default: "auto"
​
size
'default' | 'short' | 'icon'
Button size variant:
  • 'default': Full text (“Sign in with YouVersion”)
  • 'short': Short text (“Sign in”)
  • 'icon': Icon only (YouVersion logo)
Default: "default"
​
variant
'default' | 'outline'
Button style:
  • 'default': Solid background
  • 'outline': Border with transparent background
Default: "default"
​
radius
'rounded' | 'rectangular'
Corner style:
  • 'rounded': Default rounded corners
  • 'rectangular': More rectangular (0.65rem radius)
Default: "rounded"
​
text
string
Custom button text. Overrides default text based on mode and size.
​
redirectUrl
string
OAuth redirect URL.Deprecated: Use authRedirectUrl on YouVersionProvider instead.
​
scopes
AuthenticationScopes[]
OAuth scopes to request (e.g., ['profile']).Default: []
​
onAuthError
(error: Error) => void
Callback when authentication fails.
​
onClick
(e: React.MouseEvent<HTMLButtonElement>) => void
Additional click handler (called before auth flow).
​
disabled
boolean
Whether the button is disabled.Default: false

​
Examples

​
Auto Mode (Default)

Shows sign in when not authenticated, sign out when authenticated: 
<YouVersionAuthButton
  onAuthError={(error) => console.error(error)}
/>

​
Sign In Only

<YouVersionAuthButton
  mode="signIn"
  onAuthError={(error) => console.error(error)}
/>

​
Sign Out Only

<YouVersionAuthButton
  mode="signOut"
  onAuthError={(error) => console.error(error)}
/>

​
Short Size

<YouVersionAuthButton
  size="short"
  onAuthError={(error) => console.error(error)}
/>

​
Icon Only

<YouVersionAuthButton
  size="icon"
  onAuthError={(error) => console.error(error)}
/>

​
Outline Variant

<YouVersionAuthButton
  variant="outline"
  onAuthError={(error) => console.error(error)}
/>

​
Rectangular Corners

<YouVersionAuthButton
  radius="rectangular"
  onAuthError={(error) => console.error(error)}
/>

​
Dark Theme

<YouVersionAuthButton
  background="dark"
  onAuthError={(error) => console.error(error)}
/>

​
Custom Text

<YouVersionAuthButton
  text="Login to Continue"
  onAuthError={(error) => console.error(error)}
/>

​
With Scopes

<YouVersionAuthButton
  scopes={['profile']}
  onAuthError={(error) => console.error(error)}
/>

​
All Options Combined

<YouVersionAuthButton
  mode="auto"
  size="short"
  variant="outline"
  radius="rectangular"
  background="dark"
  scopes={['profile']}
  onAuthError={(error) => {
    console.error('Auth failed:', error);
    // Show error toast
  }}
/>

​
Button Text

The button displays different text based on mode, size, and auth state:
ModeSizeNot AuthenticatedAuthenticated
autodefault”Sign in with YouVersion""Sign out of YouVersion”
autoshort”Sign in""Sign out”
autoicon(icon only)(icon only)
signIndefault”Sign in with YouVersion""Sign in with YouVersion”
signInshort”Sign in""Sign in”
signOutdefault”Sign out of YouVersion""Sign out of YouVersion”
signOutshort”Sign out""Sign out”
The text prop overrides all default text.

​
Loading State

When authentication is in progress:
  • Button shows loading spinner overlay
  • Button is disabled
  • Text remains visible but faded

​
Authentication Flow

​
Sign In

  1. User clicks button
  2. signIn() is called with scopes and redirect URL
  3. User is redirected to YouVersion OAuth
  4. After approval, redirected back to authRedirectUrl
  5. Access token stored in auth provider

​
Sign Out

  1. User clicks button
  2. signOut() is called
  3. Auth state cleared
  4. User shown as signed out

​
Error Handling

Provide onAuthError to handle authentication errors: 
<YouVersionAuthButton
  onAuthError={(error) => {
    if (error.message.includes('popup')) {
      showToast('Please allow popups for sign in');
    } else {
      showToast('Sign in failed. Please try again.');
    }
  }}
/>

​
Accessibility

  • Button uses semantic <button> element
  • Loading state announced to screen readers
  • Icon-only variant has sr-only text
  • Disabled state properly handled

​
Styling

The button includes:
  • YouVersion logo icon
  • Customizable colors via theme
  • Border color based on theme
  • Shadow effects
  • Hover and active states
  • Loading spinner overlay

​
Best Practices

  1. Always provide onAuthError to handle edge cases
  2. Use auto mode for most cases (handles both states)
  3. Use icon size in compact UIs like toolbars
  4. Test sign-out flow - ensure users can sign back in
  5. Configure redirectUrl on provider instead of each button

Build docs developers (and LLMs) love

Get started for freeTalk to us