React SDK

Components

Copy page

Installation

Install the packages with your preferred package manager:

Requirements

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

---

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;
  theme?: "light" | "dark" | "system";
}

// 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.

BibleCard

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

Code
import { BibleCard } from "@youversion/platform-react-ui";

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

Types
type BibleCardProps = {
  /** USFM passage reference (e.g., "JHN.3.16") */
  reference: string;
  /** Bible version identifier */
  versionId: number;
  /** Theme variant: light or dark */
  background?: "light" | "dark";
  /** Show version picker (default: false) */
  showVersionPicker?: boolean;
};

---

BibleTextView

Display any Bible passage with proper formatting.

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

function MyComponent() {
  return (
    <BibleTextView
      reference="JHN.3.16"
      versionId={3034}
      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;
};

---

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 Bible Version when uncontrolled */
  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>;

Code
import { useState } from "react";
import { BibleReader } from "@youversion/platform-react-ui";

// 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: 3034 - BSB) */
  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={3034}
      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={3034}
>
  <BibleChapterPicker.Trigger />
</BibleChapterPicker.Root>

// Uncontrolled: Component manages state internally
<BibleChapterPicker.Root
  defaultBook="GEN"
  defaultChapter="1"
  versionId={3034}
>
  <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={3034}
>
  <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 { useState } from "react";
import { BibleVersionPicker } from "@youversion/platform-react-ui";

export default function Page() {
  const [versionId, setVersionId] = useState(3034);

  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 } from "@youversion/platform-react-ui";

export default function LoginPage() {
  return (
    <YouVersionAuthButton
      scopes={['email', 'profile']}
      onAuthError={(error) => console.error("Auth error:", error)}
    />
  );
}

Props:

Code
// Valid OAuth scope values
type AuthenticationScopes = 'profile' | 'email';

interface YouVersionAuthButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  /** OAuth scopes (optional, defaults to empty array) */
  scopes?: AuthenticationScopes[];
  /** @deprecated Use `authRedirectUrl` on `YouVersionProvider` instead */
  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;
}

See also: AuthenticationScopes

Examples:

Code
// Different variants
<YouVersionAuthButton variant="outline" />

// Dark theme
<YouVersionAuthButton background="dark" />

// Icon only
<YouVersionAuthButton size="icon" />

// With custom text
<YouVersionAuthButton text="Custom Sign In/Out" />

// Explicit sign-in mode
<YouVersionAuthButton mode="signIn" />

// Explicit sign-out mode
<YouVersionAuthButton mode="signOut" />

// Auto mode (default) - shows sign-in when not authenticated, sign-out when authenticated
<YouVersionAuthButton mode="auto" />

// Request profile and email scopes
<YouVersionAuthButton scopes={['profile', 'email']} />