SDKs

React SDK

Copy page

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.

Getting Started

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

1. 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 (this should point to your app's main page, not a callback page)

2. Install

Code
 
npm install @youversion/platform-react-ui

3. Add Provider

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

Code
 
import { YouVersionProvider } from '@youversion/platform-react-ui'

function App() {
  return (
    <YouVersionProvider
      appKey="YOUR_APP_KEY"
      includeAuth={true}
      authRedirectUrl="https://yourapp.com"
    >
      {/* Your app */}
    </YouVersionProvider>
  )
}

4. Display a Verse

Code
 
import { BibleWidgetView } from '@youversion/platform-react-ui'

function MyComponent() {
  return (
      <BibleWidgetView
        reference="JHN.3.16"
        versionId={111}
      />
  )
}

5. Add Authentication Button (Sign in/Sign out) (Optional)

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

function MyComponent() {
  return (
    <YouVersionAuthButton
      redirectUrl="https://yourapp.com"
    />
  );
}

6. Use Authentication hook to get user information

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

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

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

  if (!auth.isAuthenticated) {
    return <div>Please sign in</div>;
  }

  return (
    <div>
      <h2>Welcome, {userInfo?.name}!</h2>
      <p>Email: {userInfo?.email}</p>
      <p>User ID: {userInfo?.userId}</p>
      <YouVersionAuthButton
        mode="signOut"
        redirectUrl="https://yourapp.com"
      />
    </div>
  );
}

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

Requirements

• React 19.1.0 or higher
• react-dom 19.1.0 or higher

Installation

Install the packages with your preferred package manager:

Code
 
npm install @youversion/platform-react-ui

Code
 
npm install @youversion/platform-react-hooks

Code
 
yarn add @youversion/platform-react-ui

Code
 
yarn add @youversion/platform-react-hooks

Code
 
pnpm add @youversion/platform-react-ui

Code
 
pnpm add @youversion/platform-react-hooks

Providers

YouVersionProvider

Required provider that configures the YouVersion Platform SDK. Wrap all your code which accesses YouVersion Platform features with YouVersionProvider. Authentication is optional and can be enabled with the includeAuth prop. If you set includeAuth={true} you must provide an authRedirectUrl.

Code
 
import { YouVersionProvider } from '@youversion/platform-react-ui'

function App() {
  return (
    <YouVersionProvider
      appKey="YOUR_APP_KEY"
      includeAuth={true}
      authRedirectUrl="https://yourapp.com"
    >
      {/* Your app */}
    </YouVersionProvider>
  )
}

Props:

The YouVersionProvider uses conditional props for TypeScript safety:

Code
 
// Base props
interface YouVersionProviderPropsBase {
  children: ReactNode;
  appKey: string;
  apiHost?: string;
}

// With authentication (authRedirectUrl becomes required when includeAuth is true)
interface YouVersionProviderPropsWithAuth extends YouVersionProviderPropsBase {
  authRedirectUrl: string;
  includeAuth: true;
}

// Without authentication (authRedirectUrl cannot be used when includeAuth is false)
interface YouVersionProviderPropsWithoutAuth extends YouVersionProviderPropsBase {
  includeAuth?: false;
  authRedirectUrl?: never;
}

// Final type is a union of the two configurations
type YouVersionProviderProps = YouVersionProviderPropsWithAuth | YouVersionProviderPropsWithoutAuth;

Components

The UI package includes fully styled, production-ready components for common Bible integration patterns.

BibleWidgetView

Pre-styled widget displaying a Bible passage with reference, text, and attribution.

Code
 
import { BibleWidgetView } from '@youversion/platform-react-ui'

export default function Page() {
  return (
    <BibleWidgetView
      reference="JHN.3.16"
      versionId={111}
      background="light"
    />
  )
}

Types
 
type BibleWidgetViewProps = {
  /** USFM passage reference (e.g., "JHN.3.16") */
  reference: string;
  /** Bible version identifier */
  versionId: number;
  /** Theme variant: light or dark */
  background?: 'light' | 'dark';
};

---

BibleTextView

Display any Bible passage with proper formatting.

Code
 
import { BibleTextView } from '@youversion/platform-react-ui'

const BIBLE_VERSION_ID = 111;
function MyComponent() {
  const version = useVersion(BIBLE_VERSION_ID);

  return (
    <BibleTextView
      reference="JHN.3.16"
      versionId={111}
      fontFamily="serif"
      fontSize={20}
      lineHeight={1.5}
    />
  )
}

Props:

Code
 
type BibleTextViewProps = {
  /** USFM reference (e.g., "JHN.3.16" or "PSA.23.1-6") */
  reference: string;
  /** Bible version ID */
  versionId: number;
  /** Font customization */
  fontFamily?: string;
  fontSize?: number;
  lineHeight?: number;
  /** Show verse numbers (default: true) */
  showVerseNumbers?: boolean;
  /** Show footnotes (default: true) */
  renderNotes?: boolean;
};

Important: When using the BibleTextView component, you are responsible for displaying any required Bible version copyright notice, as required by the license. This component gives you full flexibility over layout, so be sure to add copyright or attribution credits yourself where appropriate in your UI.

If you want these credits handled for you automatically, use the BibleWidgetView component instead.

---

BibleReader

A complete Bible reading experience with version picker, chapter navigation, and customizable text display.

Code
 
import { BibleReader } from '@youversion/platform-react-ui'

function App() {
  return (
    <div className="h-screen">
      <BibleReader.Root>
        <BibleReader.Content />
        <BibleReader.Toolbar />
      </BibleReader.Root>
    </div>
  )
}

Sub-components:

• BibleReader.Root - Container with context provider
• BibleReader.Content - Displays passage text with book/chapter header
• BibleReader.Toolbar - Version and chapter picker controls

Root Props:

Code
 
type BibleReaderRootProps = {
  /** Controlled book ID (3-letter USFM code like "JHN") */
  book?: string;
  /** Default book when uncontrolled */
  defaultBook?: string;
  onBookChange?: (book: string) => void;
  
  /** Controlled chapter number */
  chapter?: string;
  /** Default chapter when uncontrolled */
  defaultChapter?: string;
  onChapterChange?: (chapter: string) => void;
  
  /** Controlled version ID */
  versionId?: number;
  /** Default version when uncontrolled (default: 111 - NIV) */
  defaultVersionId?: number;
  onVersionChange?: (versionId: number) => void;
  
  /** Font customization */
  fontFamily?: string;
  fontSize?: number;
  lineHeight?: number;
  
  /** Toggle verse numbers (default: true) */
  showVerseNumbers?: boolean;
  
  /** Theme (default: "light") */
  background?: "light" | "dark";
  
  children?: ReactNode;
};

Toolbar Props:

Code
 
{ border = 'top' }: { border?: 'top' | 'bottom' }

Examples:

Code
 
// Dark theme with custom styling
<BibleReader.Root 
  background="dark"
  fontSize={18}
  lineHeight={2.0}
  showVerseNumbers={false}
>
  <BibleReader.Toolbar border="bottom" />
  <BibleReader.Content />
</BibleReader.Root>

// Controlled state
function ControlledReader() {
  const [book, setBook] = useState('PSA')
  const [chapter, setChapter] = useState('23')
  
  return (
    <BibleReader.Root
      book={book}
      chapter={chapter}
      onBookChange={setBook}
      onChapterChange={setChapter}
    >
      <BibleReader.Content />
      <BibleReader.Toolbar />
    </BibleReader.Root>
  )
}

---

VerseOfTheDay

Display the YouVersion Verse of the Day.

Code
 
import { VerseOfTheDay } from '@youversion/platform-react-ui'

function MyApp() {
  return <VerseOfTheDay />
}

Props:

Code
 
type VerseOfTheDayProps = {
  /** Bible version ID (default: 1 - KJV) */
  versionId?: number;
  /** Day of year (1-366). Defaults to today */
  dayOfYear?: number;
  /** Show decorative sun icon (default: true) */
  showSunIcon?: boolean;
  /** Show Bible App attribution (default: true) */
  showBibleAppAttribution?: boolean;
  /** Show share button (default: true) */
  showShareButton?: boolean;
  /** Card size (default: "default") */
  size?: "default" | "lg";
};

---

BibleChapterPicker

Popover-based interface for selecting books and chapters.

Code
 
import { BibleChapterPicker } from '@youversion/platform-react-ui';
import useState from 'react';

export default function Page() {
  const [currentBook, setCurrentBook] = useState("JHN")
  const [currentChapter, setCurrentChapter] = useState(1)
  return (
    <BibleChapterPicker.Root 
      versionId={111} 
      defaultBook={currentBook}
      onBookChange={(book) => console.log(book)}
      onChapterChange={(chapter) => console.log(chapter)}
    >
      <BibleChapterPicker.Trigger>
        Select Chapter
      </BibleChapterPicker.Trigger>
    </BibleChapterPicker.Root>
  )
}

BibleChapterPicker.Root

Types
 
type RootProps = {
  /** Controlled Book */
  book?: BibleBook['id'];
  /** Uncontrolled Book (default: ''), example "JHN" */
  defaultBook?: BibleBook['id'];
  onBookChange?: (book: BibleBook['id']) => void;
  /** Controlled Chapter */
  chapter?: string;
  /** Uncontrolled Chapter (default: ''), example "1" */
  defaultChapter?: string;
  onChapterChange?: (chapter: string) => void;
  versionId: number;
  background?: 'light' | 'dark';
  children?: ReactNode;
};

Controlled vs Uncontrolled Usage:

The book/defaultBook and chapter/defaultChapter props follow the React controlled/uncontrolled component pattern:

Code
 
// Controlled: Parent manages state
const [book, setBook] = useState('GEN');
const [chapter, setChapter] = useState('1');

<BibleChapterPicker.Root
  book={book}
  onBookChange={setBook}
  chapter={chapter}
  onChapterChange={setChapter}
  versionId={111}
>
  <BibleChapterPicker.Trigger />
</BibleChapterPicker.Root>

// Uncontrolled: Component manages state internally
<BibleChapterPicker.Root
  defaultBook="GEN"
  defaultChapter="1"
  versionId={111}
>
  <BibleChapterPicker.Trigger />
</BibleChapterPicker.Root>

// Mixed: Uncontrolled with change notifications
<BibleChapterPicker.Root
  defaultBook="GEN"
  onBookChange={(b) => console.log('Book changed:', b)}
  onChapterChange={(c) => console.log('Chapter changed:', c)}
  versionId={111}
>
  <BibleChapterPicker.Trigger />
</BibleChapterPicker.Root>

See also: BibleBook

BibleChapterPicker.Trigger

The button or component that toggles the Bible Chapter Picker popover.

---

BibleVersionPicker

Popover-based interface for selecting Bible versions with language filtering and search.

Code
 
import { BibleVersionPicker } from '@youversion/platform-react-ui'

export default function Page() {
  const [versionId, setVersionId] = useVersionId(111)
  return (
    <BibleVersionPicker.Root 
      versionId={versionId}
      onVersionChange={setVersionId}
    >
      <BibleVersionPicker.Trigger>
        Select Version
      </BibleVersionPicker.Trigger>
      <BibleVersionPicker.Content />
    </BibleVersionPicker.Root>
  )
}

BibleVersionPicker.Root

Types
 
type RootProps = {
  versionId: number;
  onVersionChange?: (versionId: number) => void;
  background?: 'light' | 'dark';
  /** side that the popover renders from the trigger (default: 'top') */
  side?: 'top' | 'right' | 'bottom' | 'left';
  children?: ReactNode;
};

See also: BibleVersion

BibleVersionPicker.Trigger

The button or component that toggles the Bible Version Picker popover. Shows the current version's abbreviation.

BibleVersionPicker.Content

The popover content displaying available versions with language selection, search, and filtering.

---

YouVersionAuthButton

Pre-styled button for YouVersion authentication with multiple variants and themes that can handle both sign-in and sign-out.

Code
 
import { YouVersionAuthButton, SignInWithYouVersionPermission } from '@youversion/platform-react-ui'

export default function LoginPage() {
  return (
    <YouVersionAuthButton
      redirectUrl="https://yourapp.com"
      onAuthError={(error) => console.error('Auth error:', error)}
    />
  )
}

Props:

Code
 
interface YouVersionAuthButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  /** OAuth scopes (optional, defaults to empty array) */
  scopes?: AuthenticationScopes[];
  /** OAuth redirect URL (required) */
  redirectUrl: string;
  /** Error handler for authentication errors */
  onAuthError?: (error: Error) => void;
  /** Button variant (default: "default") */
  variant?: "default" | "outline";
  /** Button size (default: "default") */
  size?: "default" | "short" | "icon";
  /** Theme variant (default: "light") */
  background?: "light" | "dark";
  /** Border radius (default: "rounded") */
  radius?: "rounded" | "rectangular";
  /** Button mode (default: "auto") */
  mode?: "signIn" | "signOut" | "auto";
  /** Custom text for the button */
  text?: string;
}

Examples:

Code
 
// Different variants
<YouVersionAuthButton
  variant="outline"
  redirectUrl="https://yourapp.com"
/>

// Dark theme
<YouVersionAuthButton
  background="dark"
  redirectUrl="https://yourapp.com"
/>

// Icon only
<YouVersionAuthButton
  size="icon"
  redirectUrl="https://yourapp.com"
/>

// With custom text
<YouVersionAuthButton
  redirectUrl="https://yourapp.com"
  text="Custom Sign In/Out"
/>

// Explicit sign-in mode
<YouVersionAuthButton
  mode="signIn"
  redirectUrl="https://yourapp.com"
/>

// Explicit sign-out mode
<YouVersionAuthButton
  mode="signOut"
  redirectUrl="https://yourapp.com"
/>

// Auto mode (default) - shows sign-in when not authenticated, sign-out when authenticated
<YouVersionAuthButton
  mode="auto"
  redirectUrl="https://yourapp.com"
/>

// With OAuth scopes
<YouVersionAuthButton
  redirectUrl="https://yourapp.com"
  scopes={['profile', 'email']}
/>

Authentication Hooks

useYVAuth

Main hook for managing YouVersion authentication state. Provides access to authentication status, user information, and sign-out functionality.

Code
 
import { useYVAuth } from '@youversion/platform-react-ui'

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

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

  if (!auth.isAuthenticated) {
    return <div>Please sign in</div>;
  }

  return (
    <div>
      <h2>Welcome, {userInfo?.name}!</h2>
      <p>Email: {userInfo?.email}</p>
      <p>User ID: {userInfo?.userId}</p>
      <button onClick={() => signOut()}>Sign Out</button>
    </div>
  );
}

Return Types:

Code
 
type UseYVAuthReturn = {
  auth: AuthenticationState;
  userInfo: YouVersionUserInfo | null;
  signIn: (params: { redirectUrl: string; scopes?: AuthenticationScopes[] }) => Promise<void>;
  signOut: () => void;
  processCallback: () => Promise<SignInWithYouVersionResult | null>;
};

interface AuthenticationState {
    isAuthenticated: boolean;
    isLoading: boolean;
    accessToken: string | null;
    idToken: string | null;
    result: SignInWithYouVersionResult | null;
    error: Error | null;
}

type SignInWithYouVersionResultProps = {
    accessToken?: string;
    expiresIn?: number;
    refreshToken?: string;
    idToken?: string;
    yvpUserId?: string;
    name?: string;
    profilePicture?: string;
    email?: string;
};
declare class SignInWithYouVersionResult {
    readonly accessToken: string | undefined;
    readonly expiryDate: Date | undefined;
    readonly refreshToken: string | undefined;
    readonly idToken: string | undefined;
    readonly yvpUserId: string | undefined;
    readonly name: string | undefined;
    readonly profilePicture: string | undefined;
    readonly email: string | undefined;
    constructor({ accessToken, expiresIn, refreshToken, idToken, yvpUserId, name, profilePicture, email, }: SignInWithYouVersionResultProps);
}

interface YouVersionUserInfoJSON {
    name?: string;
    id?: string;
    avatar_url?: string;
    email?: string;
}
declare class YouVersionUserInfo {
    readonly name?: string;
    readonly userId?: string;
    readonly email?: string;
    readonly avatarUrlFormat?: string;
    constructor(data: YouVersionUserInfoJSON);
    getAvatarUrl(width?: number, height?: number): URL | null;
    get avatarUrl(): URL | null;
}

Bible Content Hooks

useBibleClient

Returns a configured BibleClient instance for direct API calls.

Code
 
import { useBibleClient } from '@youversion/platform-react-hooks'

function MyComponent() {
  const bibleClient = useBibleClient()
  
  const fetchData = async () => {
    const versions = await bibleClient.getVersions('en*')
  }
}

useVersion

Fetches a specific Bible version by ID.

Code
 
import { useVersion } from '@youversion/platform-react-hooks'

function VersionInfo({ versionId }) {
  const { version, loading, error } = useVersion(versionId)
  
  if (loading) return <div>Loading...</div>
  if (error) return <div>Error: {error.message}</div>
  
  return (
    <div>
      <h2>{version?.title}</h2>
      <p>{version?.abbreviation}</p>
    </div>
  )
}

Code
 
export function useVersion(
  versionId: number,
  options?: UseApiDataOptions,
): {
  version: BibleVersion | null;
  loading: boolean;
  error: Error | null;
  refetch: () => void;
}

See also: BibleVersion, UseApiDataOptions

useVersions

Fetches Bible versions filtered by language.

Code
 
import { useVersions } from '@youversion/platform-react-hooks'

function VersionList() {
  const { versions, loading, error } = useVersions('en*')
  
  return (
    <div>
      {versions?.data.map((version) => (
        <div key={version.id}>{version.title}</div>
      ))}
    </div>
  )
}

Code
 
export function useVersions(
  languageRanges?: string = 'en',
  licenseId?: string | number,
  options?: UseApiDataOptions,
): {
  versions: Collection<BibleVersion> | null;
  loading: boolean;
  error: Error | null;
  refetch: () => void;
}

See also: BibleVersion, Collection, UseApiDataOptions

useFilteredVersions

Filters versions array by search term and selected language.

Code
 
import { useFilteredVersions } from '@youversion/platform-react-hooks'

function FilteredVersions() {
  const versions = useFilteredVersions(allVersions, searchTerm, selectedLanguage)
}

Code
 
export function useFilteredVersions(
  versions: BibleVersion[],
  searchTerm: string,
  selectedLanguage: string,
): BibleVersion[]

See also: BibleVersion

useBook

Fetches a specific book from a Bible version.

Code
 
import { useBook } from '@youversion/platform-react-hooks'

function BookInfo({ versionId, bookCode }) {
  const { book, loading, error } = useBook(versionId, bookCode)
  
  return (
    <div>
      <h2>{book?.title}</h2>
      <p>Chapters: {book?.chapters?.length}</p>
    </div>
  )
}

Code
 
export function useBook(
  versionId: number,
  book: string,
  options?: UseApiDataOptions,
): {
  book: BibleBook | null;
  loading: boolean;
  error: Error | null;
  refetch: () => void;
}

See also: BibleBook, UseApiDataOptions

useBooks

Fetches all books from a Bible version.

Code
 
import { useBooks } from '@youversion/platform-react-hooks'

function BookList({ versionId }) {
  const { books, loading, error } = useBooks(versionId)
  
  return (
    <div>
      {books?.data.map((book) => (
        <div key={book.id}>{book.title}</div>
      ))}
    </div>
  )
}

Code
 
export function useBooks(
  versionId: number,
  options?: UseApiDataOptions,
): {
  books: Collection<BibleBook> | null;
  loading: boolean;
  error: Error | null;
  refetch: () => void;
}

See also: BibleBook, Collection, UseApiDataOptions

useChapter

Fetches a specific chapter.

Code
 
import { useChapter } from '@youversion/platform-react-hooks'

function ChapterView({ versionId, bookCode, chapterNumber }) {
  const { chapter, loading, error } = useChapter(versionId, bookCode, chapterNumber)
  
  return <div>{chapter?.title}</div>
}

Code
 
export function useChapter(
  versionId: number,
  book: string,
  chapter: number,
  options?: UseApiDataOptions,
): {
  chapter: BibleChapter | null;
  loading: boolean;
  error: Error | null;
  refetch: () => void;
}

See also: BibleChapter, UseApiDataOptions

useChapters

Fetches all chapters for a book.

Code
 
import { useChapters } from '@youversion/platform-react-hooks'

function ChapterList({ versionId, bookCode }) {
  const { chapters, loading, error } = useChapters(versionId, bookCode)
  
  return (
    <div>
      {chapters?.data.map((chapter) => (
        <div key={chapter.id}>{chapter.title}</div>
      ))}
    </div>
  )
}

Code
 
export function useChapters(
  versionId: number,
  book: string,
  options?: UseApiDataOptions,
): {
  chapters: Collection<BibleChapter> | null;
  loading: boolean;
  error: Error | null;
  refetch: () => void;
}

See also: BibleChapter, Collection, UseApiDataOptions

useVerse

Fetches a specific verse.

Code
 
import { useVerse } from '@youversion/platform-react-hooks'

function VerseDisplay({ versionId, bookCode, chapterNumber, verseNumber }) {
  const { verse, loading, error } = useVerse(versionId, bookCode, chapterNumber, verseNumber)
  
  return <p>{verse?.reference}</p>
}

Code
 
export function useVerse(
  versionId: number,
  book: string,
  chapter: number,
  verse: number,
  options?: UseApiDataOptions,
): {
  verse: BibleVerse | null;
  loading: boolean;
  error: Error | null;
  refetch: () => void;
}

See also: BibleVerse, UseApiDataOptions

useVerses

Fetches all verses for a chapter.

Code
 
import { useVerses } from '@youversion/platform-react-hooks'

function ChapterVerses({ versionId, bookCode, chapterNumber }) {
  const { verses, loading, error } = useVerses(versionId, bookCode, chapterNumber)
  
  return (
    <div>
      {verses?.data.map((verse) => (
        <p key={verse.id}>{verse.reference}</p>
      ))}
    </div>
  )
}

Code
 
export function useVerses(
  versionId: number,
  book: string,
  chapter: number,
  options?: UseApiDataOptions,
): {
  verses: Collection<BibleVerse> | null;
  loading: boolean;
  error: Error | null;
  refetch: () => void;
}

See also: BibleVerse, Collection, UseApiDataOptions

usePassage

Fetches a Bible passage with formatted content. Recommended for retrieving verse text to preserve formatting.

Code
 
import { usePassage } from '@youversion/platform-react-hooks'

function BiblePassage({ versionId, usfm }) {
  const { passage, loading, error } = usePassage(versionId, usfm, 'html', true, false)
  
  if (loading) return <div>Loading...</div>
  
  return (
    <div>
      <h2>{passage?.human_reference}</h2>
      <div dangerouslySetInnerHTML={{ __html: passage?.content || '' }} />
    </div>
  )
}

Types
 
type usePassageProps = {
  versionId: number;
  usfm: string;
  format?: 'html' | 'text';
  include_headings?: boolean;
  include_notes?: boolean;
  options?: UseApiDataOptions;
};

export function usePassage({
  versionId,
  usfm,
  format = 'html',
  include_headings = false,
  include_notes = false,
  options
  }: usePassageProps): {
  passage: BiblePassage | null;
  loading: boolean;
  error: Error | null;
  refetch: () => void;
}

See also: BiblePassage, UseApiDataOptions

useVerseOfTheDay

Fetches the Verse of the Day.

Code
 
import { useVerseOfTheDay } from '@youversion/platform-react-hooks'

function DailyVerse() {
  const dayOfYear = Math.floor((new Date() - new Date(new Date().getFullYear(), 0, 0)) / 86400000)
  const { data: votd, loading, error } = useVerseOfTheDay(dayOfYear)
  
  return <p>Day {votd?.day}: {votd?.passage_id}</p>
}

Code
 
export function useVerseOfTheDay(
  day: number,
  options?: UseApiDataOptions,
): {
  data: VOTD | null;
  loading: boolean;
  error: Error | null;
  refetch: () => void;
}

See also: VOTD, UseApiDataOptions

useLanguages

Fetches available languages.

Code
 
import { useLanguages } from '@youversion/platform-react-hooks'

function LanguageList() {
  const { languages, loading, error } = useLanguages({ country: 'US' })
  
  return (
    <div>
      {languages?.data.map((language) => (
        <div key={language.id}>{language.display_names.en}</div>
      ))}
    </div>
  )
}

Code
 
export function useLanguages(
  options: GetLanguagesOptions,
  apiOptions?: UseApiDataOptions,
): {
  languages: Collection<Language> | null;
  loading: boolean;
  error: Error | null;
  refetch: () => void;
}

See also: Language, Collection, GetLanguagesOptions, UseApiDataOptions

Referenced Types

All types are imported from @youversion/platform-core. For complete type definitions and details, see the TypeScript Types page.

Core Types:

• BibleVersion - Bible translation metadata
• BibleBook - Book of the Bible
• BibleChapter - Chapter with verses
• BibleVerse - Single verse
• BiblePassage - Formatted passage content
• Collection<T> - Paginated API response wrapper
• Language - Language metadata
• VOTD - Verse of the Day response

Hook Options:

• UseApiDataOptions - { enabled?: boolean } - Control hook execution
• GetLanguagesOptions - { country?: string; page_size?: number; page_token?: string } - Language filtering

Migration from Legacy Authentication

If you're upgrading from a previous version that used YVPProvider and callback-based authentication, follow these steps:

Breaking Changes Summary

1. Provider Change: BibleSDKProvider → YouVersionProvider (complete replacement, no backwards compatibility)
2. Authentication Provider: YVPProvider eliminated - auth now integrated into YouVersionProvider
3. Hook Change: useAuthentication() → useYVAuth()
4. SignInButton Props: Simplified scopes and removed success callbacks
5. No Callback Page: OAuth redirects directly to your app (no /auth/callback needed)
6. JWT-based User Info: User information extracted from tokens (no /auth/me API calls)

Step-by-Step Migration

1. Update Your Provider

Before (Legacy SDK):

Code
 
// Old separate providers approach
import { YVPProvider, BibleSDKProvider } from '@youversion/platform-react-ui'

<YVPProvider config={{ appKey, redirectUri }}>
  <BibleSDKProvider appKey={appKey}>
    {children}
  </BibleSDKProvider>
</YVPProvider>

// OR just Bible content without auth
<BibleSDKProvider appKey={appKey}>
  {children}
</BibleSDKProvider>

After (Current SDK):

Code
 
import { YouVersionProvider } from '@youversion/platform-react-ui'

// With authentication
<YouVersionProvider
  appKey={appKey}
  includeAuth={true}
  authRedirectUrl={redirectUri}
>
  {children}
</YouVersionProvider>

// Bible content only (no auth)
<YouVersionProvider appKey={appKey}>
  {children}
</YouVersionProvider>

2. Update Authentication Hook Usage

Before:

Code
 
import { useAuthentication } from '@youversion/platform-react-ui'

const { isAuthenticated, signOut, userInfo } = useAuthentication();

After:

Code
 
import { useYVAuth } from '@youversion/platform-react-ui'

const { auth, signOut, userInfo } = useYVAuth();
// auth.isAuthenticated, auth.isLoading, auth.error

3. Update SignInButton to YouVersionAuthButton

Before:

Code
 
<SignInButton
  requiredPermissions={[SignInWithYouVersionPermission.bibles]}
  optionalPermissions={[SignInWithYouVersionPermission.highlights]}
  onSuccess={handleSuccess}
  onAuthError={handleError}
/>

After:

Code
 
<YouVersionAuthButton
  scopes={['profile', 'email']} // Optional, defaults to []
  redirectUrl={redirectUrl}
  onAuthError={handleError}
  mode="auto" // Optional: auto (default), signIn, or signOut
  // No onSuccess needed - state updates automatically
/>

4. Remove Callback Page

• Delete your /auth/callback page/route entirely
• Remove any WebAuthenticationStrategy.handleCallback() logic
• Update your OAuth app settings to redirect to your main app URL

5. Update Environment Variables

Before:

Code
 
NEXT_PUBLIC_REDIRECT_URI=https://yourapp.com/auth/callback

After:

Code
 
NEXT_PUBLIC_REDIRECT_URI=https://yourapp.com

Benefits of New Implementation

• ✅ Simpler Setup: No callback page required
• ✅ Enhanced Security: PKCE OAuth flow
• ✅ Better Performance: Direct JWT parsing, no additional API calls
• ✅ Unified Provider: Single provider for all features
• ✅ Automatic State Management: Authentication state updates automatically

Environment Variables

For Next.js applications, add these environment variables:

Code
 
# Required: Your YouVersion Platform App Key
NEXT_PUBLIC_YVP_APP_KEY=your-app-key-here

# Required for Authentication: OAuth redirect URL
NEXT_PUBLIC_REDIRECT_URI=https://yourapp.com

# Optional: API host (defaults to api.youversion.com)
NEXT_PUBLIC_YVP_API_HOST=api.youversion.com

Copyright & Attribution

The UI components BibleWidgetView, BibleReader.Content, and VerseOfTheDay automatically display copyright from version.copyright after the passage text.

If you're displaying scripture without using one of those components, you are responsible for displaying appropriate attribution yourself. For example:

Code
 
function CustomPassage() {
  const { passage } = usePassage(111, 'JHN.3.16')
  const { version } = useVersion(111)
  
  return (
    <div>
      <div dangerouslySetInnerHTML={{ __html: passage?.content }} />
      {version?.copyright && (
        <p className="text-sm text-gray-600">
          {version.copyright}
        </p>
      )}
    </div>
  )
}

The copyright text comes from the BibleVersion object:

• copyright - Brief attribution (use after verses)
• promotional_content - Full copyright notice (use in settings/about pages)

Theming

The React SDK uses scoped CSS variables prefixed with --yv- to avoid conflicts with your app.

Passing Your App's Theme

Pass your app's theme to YouVersionProvider using the theme prop. This allows SDK components to automatically match your app's light/dark mode:

Code
 
import { YouVersionProvider } from '@youversion/platform-react-ui'

function App() {
  const [theme, setTheme] = useState<'light' | 'dark'>('light')

  return (
    <YouVersionProvider
      appKey="YOUR_APP_KEY"
      theme={theme}
    >
      {/* SDK components will automatically use the correct theme */}
      <BibleWidgetView reference="JHN.3.16" versionId={111} />
    </YouVersionProvider>
  )
}

When theme is set on the provider, all child components will inherit it. You can still override the theme on individual components using their background prop:

Code
 
<YouVersionProvider appKey="YOUR_APP_KEY" theme="dark">
  {/* Uses dark theme from provider */}
  <BibleWidgetView reference="JHN.3.16" versionId={111} />
  
  {/* Overrides to light theme */}
  <BibleReader.Root background="light">
    <BibleReader.Content />
  </BibleReader.Root>
</YouVersionProvider>

Customization Examples

Custom Bible Reader Font:

CSS
 
[data-yv-sdk] {
  --yv-reader-font-family: 'Georgia', 'Times New Roman', serif;
  --yv-reader-font-size: 20px;
  --yv-reader-line-height: 1.8;
  --yv-reader-letter-spacing: 0.02em;
}