YouVersion Platform React SDK

A comprehensive React SDK for integrating YouVersion Platform features into your web applications. This monorepo provides a type-safe API client, React hooks, and ready-to-use components for Bible content.

Quick Start

NPM packages

This repo contains the source code for three NPM packages which we advise that you install directly:

• UI components: @youversion/platform-react-ui
• React hooks: @youversion/platform-react-hooks
• Direct API access: @youversion/platform-core

Installation

# For UI components
pnpm add @youversion/platform-react-ui

# For React hooks only
pnpm add @youversion/platform-react-hooks

# For direct API access
pnpm add @youversion/platform-core

Quick Start Examples

UI Components

To display a verse, or a range of verses:

import { BibleSDKProvider, BibleTextView } from '@youversion/platform-react-ui';

function App() {
  return (
    <BibleSDKProvider appKey={"YOUR_APP_KEY"}>
      <BibleTextView reference="JHN.1.1-4" versionId={111} />
    </BibleSDKProvider>
  );
}

To display the YouVersion Verse of the Day:

import { BibleSDKProvider, VerseOfTheDay } from '@youversion/platform-react-ui';

function App() {
  return (
    <BibleSDKProvider appKey="YOUR_APP_KEY">
      <VerseOfTheDay versionId={111} />
    </BibleSDKProvider>
  );
}

Custom Hooks

import { BibleSDKProvider, usePassage } from '@youversion/platform-react-hooks';

function BibleVerse() {
  const { passage, loading } = usePassage({ versionId: 111, usfm: 'JHN.3.16' });
  if (loading) return <div>Loading...</div>;
  return <div dangerouslySetInnerHTML={{ __html: passage?.content || '' }} />;
}

function App() {
  return (
    <BibleSDKProvider appKey="YOUR_APP_KEY">
      <BibleVerse />
    </BibleSDKProvider>
  );
}

Core API

import { ApiClient, BibleClient } from '@youversion/platform-core';

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

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

// Fetch the html text of John 3:16 in that first Bible version
const passage = await bibleClient.getPassage(versions.data[0].id, 'JHN.3.16');
console.log(passage.content);

Contributing

Want to contribute? See CONTRIBUTING.md for setup instructions, development workflow, and guidelines.

License

This SDK is licensed under Apache 2.0.

Licensing information for the Bible versions is available at the YouVersion Platform site.