Skip to main content
This guide will walk you through building your first Bible application using the YouVersion Platform React SDK. You’ll display Bible verses, show the Verse of the Day, and learn how to fetch data with hooks.

​
Prerequisites

Before starting, make sure you have:

​
Step 1: Install the SDK

Install the UI components package, which includes everything you need: 
npm install @youversion/platform-react-ui

​
Step 2: Configure the Provider

Wrap your application with YouVersionProvider and provide your API key:
App.tsx
import { YouVersionProvider } from '@youversion/platform-react-ui';

function App() {
  return (
    <YouVersionProvider appKey="YOUR_APP_KEY">
      {/* Your components go here */}
    </YouVersionProvider>
  );
}

export default App;
Replace YOUR_APP_KEY with your actual API key from YouVersion Platform. Never commit your API key to version control.

​
Step 3: Display Your First Verse

Use the BibleTextView component to display a Bible verse: 
import { YouVersionProvider, BibleTextView } from '@youversion/platform-react-ui';

function App() {
  return (
    <YouVersionProvider appKey="YOUR_APP_KEY">
      <div style={{ padding: '2rem' }}>
        <h1>John 3:16</h1>
        <BibleTextView 
          reference="JHN.3.16" 
          versionId={3034} 
        />
      </div>
    </YouVersionProvider>
  );
}
The versionId parameter specifies which Bible translation to use. 3034 is the Berean Standard Bible. See Bible Version IDs below for more options.

​
Step 4: Show Verse of the Day

Add the VerseOfTheDay component to display today’s verse: 
import { 
  YouVersionProvider, 
  BibleTextView,
  VerseOfTheDay 
} from '@youversion/platform-react-ui';

function App() {
  return (
    <YouVersionProvider appKey="YOUR_APP_KEY">
      <div style={{ padding: '2rem' }}>
        <VerseOfTheDay 
          versionId={3034}
          showSunIcon={true}
          showShareButton={true}
          showBibleAppAttribution={true}
        />
        
        <div style={{ marginTop: '2rem' }}>
          <h2>John 3:16</h2>
          <BibleTextView reference="JHN.3.16" versionId={3034} />
        </div>
      </div>
    </YouVersionProvider>
  );
}

​
Step 5: Fetch Data with Hooks

For more control, use hooks to fetch and display Bible data: 
import { YouVersionProvider, usePassage } from '@youversion/platform-react-hooks';

function BibleVerse() {
  const { passage, loading, error } = usePassage({ 
    versionId: 3034, 
    usfm: 'JHN.3.16' 
  });

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <h2>{passage?.reference.human}</h2>
      <div dangerouslySetInnerHTML={{ __html: passage?.content || '' }} />
    </div>
  );
}

function App() {
  return (
    <YouVersionProvider appKey="YOUR_APP_KEY">
      <div style={{ padding: '2rem' }}>
        <BibleVerse />
      </div>
    </YouVersionProvider>
  );
}

​
Step 6: Build a Bible Reader

Create a complete reading experience with the BibleReader component: 
import { YouVersionProvider } from '@youversion/platform-react-ui';
import { BibleReader } from '@youversion/platform-react-ui';

function App() {
  return (
    <YouVersionProvider appKey="YOUR_APP_KEY">
      <BibleReader.Root
        versionId={3034}
        book="JHN"
        chapter="3"
        fontSize={16}
        lineHeight={1.6}
        fontFamily="Source Serif"
        showVerseNumbers={true}
        background="light"
      >
        <BibleReader.Toolbar position="top" />
        <BibleReader.Content />
      </BibleReader.Root>
    </YouVersionProvider>
  );
}
The BibleReader component includes built-in navigation controls, version picker, and settings for font customization.

​
Understanding USFM References

Bible references use the USFM (Unified Standard Format Markers) format:
  • Single verse: JHN.3.16 (John 3:16)
  • Verse range: JHN.3.16-17 (John 3:16-17)
  • Multiple verses: JHN.3.16,18 (John 3:16 and 18)
  • Entire chapter: JHN.3 (John chapter 3)
Common book abbreviations:
  • GEN - Genesis
  • PSA - Psalms
  • MAT - Matthew
  • JHN - John
  • ROM - Romans
  • REV - Revelation

​
Bible Version IDs

Here are some commonly used Bible version IDs:
Version IDNameLanguage
3034Berean Standard BibleEnglish
1King James VersionEnglish
111New International VersionEnglish
59Reina-Valera 1960Spanish
206La Bible du SemeurFrench
Use the useVersions hook or BibleClient.getVersions() method to discover all available versions and their IDs.

​
Using the Core API Directly

For non-React applications or advanced use cases, use the Core API: 
import { ApiClient, BibleClient } from '@youversion/platform-core';

const apiClient = new ApiClient({ appKey: 'YOUR_APP_KEY' });
const bibleClient = new BibleClient(apiClient);

// Get available Bible versions in English
const versions = await bibleClient.getVersions('en*');
console.log(versions.data[0].title);

// Fetch a passage
const passage = await bibleClient.getPassage(3034, 'JHN.3.16');
console.log(passage.content);

​
Next Steps

Now that you have a working application, explore these resources:

Core Concepts

Learn about the three-layer architecture

Authentication

Add user authentication to your app

Styling Guide

Customize component appearance

API Reference

Explore the complete API reference

​
Troubleshooting

​
”Invalid API key” error

Make sure you’ve obtained a valid API key from YouVersion Platform and that you’re passing it correctly to YouVersionProvider.

​
Components not rendering

Ensure that:
  1. You’ve wrapped your app with YouVersionProvider
  2. Your API key is valid
  3. You’re using React 19.1.0 or higher
  4. You’re using Node.js 20.0.0 or higher

​
TypeScript errors

If you’re using TypeScript, make sure you have the latest type definitions installed. The SDK includes full TypeScript support.

​
Getting Help

Build docs developers (and LLMs) love

Get started for freeTalk to us