React SDK

Quick Start

The React SDK provides hooks and UI components to integrate Bible content and YouVersion authentication into React applications with minimal setup. See the source on GitHub.

Which package should I install?

@youversion/platform-react-ui — Start here. Includes styled components (BibleCard, BibleReader, VerseOfTheDay, auth button) plus all data hooks. Recommended for most developers.
@youversion/platform-react-hooks — Headless data hooks only. Use this if you want full control over UI and don't need any pre-built components. Automatically installed as a dependency of platform-react-ui.

Getting Started

Get a working Bible verse display with authentication in your app in under 5 minutes.

Get Your App Key and Configure OAuth
1. Sign up at platform.youversion.com to get your free App Key
2. Configure your OAuth redirect URL in your app settings
Create a demo Vite + React app

# npm 7+, extra double-dash is needed: npm create vite@latest yv-react-sdk-demo -- --template react-ts
Install our React Component Library

npm install @youversion/platform-react-ui

Add our YouVersionProvider

Wrap your app's contents with YouVersionProvider (authentication is optional):


App.tsx
import { YouVersionProvider } from "@youversion/platform-react-ui";

export default function App() {
  return (
    <YouVersionProvider
      appKey="YOUR_APP_KEY"
      theme="light"
      includeAuth={true}
      authRedirectUrl="http://localhost:5173"
    >
      <h1>Hello, World</h1>
    </YouVersionProvider>
  );
}

The authRedirectUrl must match the redirectUrl that you specified in your YouVersion Platform app settings.

Common mistake: Forgetting to add YouVersionProvider will cause our hooks and React components to throw errors.

Display a Bible Verse


App.tsx
import { YouVersionProvider } from '@youversion/platform-react-ui'
import { BibleCard } from '@youversion/platform-react-ui'

export default function App() {
  return (
    <YouVersionProvider
      appKey="YOUR_APP_KEY"
      theme="light"
      includeAuth={true}
      authRedirectUrl="http://localhost:5173"
    >
      <main
        style={{
          minHeight: '100svh',
          display: 'grid',
          gap: '1rem',
          gridAutoRows: 'min-content',
          justifyContent: 'center',
          alignContent: 'center',
        }}
      >
        <BibleCard reference="JHN.3.16" versionId={3034} />
      </main>
    </YouVersionProvider>
  )
}

Please be mindful that global tag-based CSS will cause styling issues in our YouVersion React SDK at this time.

You may find at this point that the global CSS classes in index.css and imported into main.tsx is causing conflicts with the BibleCard component.

For now, remove the index.css import in the main.tsx file.

If you need more flexibility of layout and styles, you can use BibleTextView along with appropriate custom components of your own to display the verse reference and necessary attribution.

Add our Authentication Button (Optional)


App.tsx
import { YouVersionProvider } from "@youversion/platform-react-ui";
import { BibleCard } from "@youversion/platform-react-ui";
import { YouVersionAuthButton } from "@youversion/platform-react-ui";

export default function App() {
  return (
    <YouVersionProvider
      appKey="YOUR_APP_KEY"
      theme="light"
      includeAuth={true}
      authRedirectUrl="http://localhost:5173"
    >
      <main
        style={{
          minHeight: '100svh',
          display: 'grid',
          gap: '1rem',
          gridAutoRows: 'min-content',
          justifyContent: 'center',
          alignContent: 'center',
        }}
      >
        <BibleCard reference="JHN.3.16" versionId={3034} />
        <YouVersionAuthButton scopes={['email', 'profile']} mode="auto" />
      </main>
    </YouVersionProvider>
  );
}

Use our Authentication hook to get user information


App.tsx
import { YouVersionProvider } from "@youversion/platform-react-ui";
import { BibleCard } from "@youversion/platform-react-ui";
import { YouVersionAuthButton } from "@youversion/platform-react-ui";
import { useYVAuth } from "@youversion/platform-react-ui";

function UserProfile() {
  const { auth, userInfo } = useYVAuth();

  if (auth.isLoading) {
    return <div>Loading...</div>;
  }

  if (!auth.isAuthenticated) {
    return <YouVersionAuthButton scopes={['email', 'profile']} mode="auto" />;
  }

  return (
    <div>
      <h2>Welcome, {userInfo?.name}!</h2>
      <p>Email: {userInfo?.email}</p>
      <p>User ID: {userInfo?.userId}</p>
      <YouVersionAuthButton scopes={['email', 'profile']} mode="auto" />
    </div>
  );
}

export default function App() {
  return (
    <YouVersionProvider
      appKey="YOUR_APP_KEY"
      theme="light"
      includeAuth={true}
      authRedirectUrl="http://localhost:5173"
    >
      <main
        style={{
          minHeight: '100svh',
          display: 'grid',
          gap: '1rem',
          gridAutoRows: 'min-content',
          justifyContent: 'center',
          alignContent: 'center',
        }}
      >
        <BibleCard reference="JHN.3.16" versionId={3034} />
        <UserProfile />
      </main>
    </YouVersionProvider>
  );
}

That's it! You now have Bible content with optional YouVersion authentication in your app.

Last modified on April 2, 2026

React SDK

Quick Start

The React SDK provides hooks and UI components to integrate Bible content and YouVersion authentication into React applications with minimal setup. See the source on GitHub.

Which package should I install?

@youversion/platform-react-ui — Start here. Includes styled components (BibleCard, BibleReader, VerseOfTheDay, auth button) plus all data hooks. Recommended for most developers.
@youversion/platform-react-hooks — Headless data hooks only. Use this if you want full control over UI and don't need any pre-built components. Automatically installed as a dependency of platform-react-ui.

Getting Started

Get a working Bible verse display with authentication in your app in under 5 minutes.

Get Your App Key and Configure OAuth
1. Sign up at platform.youversion.com to get your free App Key
2. Configure your OAuth redirect URL in your app settings
Create a demo Vite + React app

# npm 7+, extra double-dash is needed: npm create vite@latest yv-react-sdk-demo -- --template react-ts
Install our React Component Library

npm install @youversion/platform-react-ui

Add our YouVersionProvider

Wrap your app's contents with YouVersionProvider (authentication is optional):


App.tsx
import { YouVersionProvider } from "@youversion/platform-react-ui";

export default function App() {
  return (
    <YouVersionProvider
      appKey="YOUR_APP_KEY"
      theme="light"
      includeAuth={true}
      authRedirectUrl="http://localhost:5173"
    >
      <h1>Hello, World</h1>
    </YouVersionProvider>
  );
}

The authRedirectUrl must match the redirectUrl that you specified in your YouVersion Platform app settings.

Common mistake: Forgetting to add YouVersionProvider will cause our hooks and React components to throw errors.

Display a Bible Verse


App.tsx
import { YouVersionProvider } from '@youversion/platform-react-ui'
import { BibleCard } from '@youversion/platform-react-ui'

export default function App() {
  return (
    <YouVersionProvider
      appKey="YOUR_APP_KEY"
      theme="light"
      includeAuth={true}
      authRedirectUrl="http://localhost:5173"
    >
      <main
        style={{
          minHeight: '100svh',
          display: 'grid',
          gap: '1rem',
          gridAutoRows: 'min-content',
          justifyContent: 'center',
          alignContent: 'center',
        }}
      >
        <BibleCard reference="JHN.3.16" versionId={3034} />
      </main>
    </YouVersionProvider>
  )
}

Please be mindful that global tag-based CSS will cause styling issues in our YouVersion React SDK at this time.

You may find at this point that the global CSS classes in index.css and imported into main.tsx is causing conflicts with the BibleCard component.

For now, remove the index.css import in the main.tsx file.

If you need more flexibility of layout and styles, you can use BibleTextView along with appropriate custom components of your own to display the verse reference and necessary attribution.

Add our Authentication Button (Optional)


App.tsx
import { YouVersionProvider } from "@youversion/platform-react-ui";
import { BibleCard } from "@youversion/platform-react-ui";
import { YouVersionAuthButton } from "@youversion/platform-react-ui";

export default function App() {
  return (
    <YouVersionProvider
      appKey="YOUR_APP_KEY"
      theme="light"
      includeAuth={true}
      authRedirectUrl="http://localhost:5173"
    >
      <main
        style={{
          minHeight: '100svh',
          display: 'grid',
          gap: '1rem',
          gridAutoRows: 'min-content',
          justifyContent: 'center',
          alignContent: 'center',
        }}
      >
        <BibleCard reference="JHN.3.16" versionId={3034} />
        <YouVersionAuthButton scopes={['email', 'profile']} mode="auto" />
      </main>
    </YouVersionProvider>
  );
}

Use our Authentication hook to get user information


App.tsx
import { YouVersionProvider } from "@youversion/platform-react-ui";
import { BibleCard } from "@youversion/platform-react-ui";
import { YouVersionAuthButton } from "@youversion/platform-react-ui";
import { useYVAuth } from "@youversion/platform-react-ui";

function UserProfile() {
  const { auth, userInfo } = useYVAuth();

  if (auth.isLoading) {
    return <div>Loading...</div>;
  }

  if (!auth.isAuthenticated) {
    return <YouVersionAuthButton scopes={['email', 'profile']} mode="auto" />;
  }

  return (
    <div>
      <h2>Welcome, {userInfo?.name}!</h2>
      <p>Email: {userInfo?.email}</p>
      <p>User ID: {userInfo?.userId}</p>
      <YouVersionAuthButton scopes={['email', 'profile']} mode="auto" />
    </div>
  );
}

export default function App() {
  return (
    <YouVersionProvider
      appKey="YOUR_APP_KEY"
      theme="light"
      includeAuth={true}
      authRedirectUrl="http://localhost:5173"
    >
      <main
        style={{
          minHeight: '100svh',
          display: 'grid',
          gap: '1rem',
          gridAutoRows: 'min-content',
          justifyContent: 'center',
          alignContent: 'center',
        }}
      >
        <BibleCard reference="JHN.3.16" versionId={3034} />
        <UserProfile />
      </main>
    </YouVersionProvider>
  );
}

That's it! You now have Bible content with optional YouVersion authentication in your app.

Last modified on April 2, 2026