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";
  /** SDK UI locale. Defaults to the browser's detected UI language. */
  locale?: string;
  /** Interface direction override. Defaults to the direction for the UI locale. */
  direction?: "ltr" | "rtl";
  permittedLanguageTags?: string[];
  permittedVersionIds?: number[];
  excludedVersionIds?: number[];
}

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

Interface direction and Scripture direction are independent. See Text direction for automatic behavior and explicit overrides.

Limit which Bible versions the SDK uses

By default, the SDK offers Bible versions in every available language. To limit that catalog, pass permittedLanguageTags, permittedVersionIds, or excludedVersionIds on YouVersionProvider. These lists are the version filter, and they exist only on the provider.

Code
<YouVersionProvider
  appKey="YOUR_APP_KEY"
  permittedLanguageTags={["en"]}
>
  {/* Your app */}
</YouVersionProvider>

Language tags follow BCP 47, such as "en" for English or "es" for Spanish.

You can also limit the catalog to specific Bible versions with permittedVersionIds:

Code
<YouVersionProvider
  appKey="YOUR_APP_KEY"
  permittedVersionIds={[111, 3034]}
>
  {/* Your app */}
</YouVersionProvider>

Version IDs are YouVersion Bible version IDs. Search for them in the Bibles directory. You can pass both permittedVersionIds and permittedLanguageTags. A version must match both lists to be used.

To exclude specific versions and leave every other available version usable, pass excludedVersionIds:

Code
<YouVersionProvider
  appKey="YOUR_APP_KEY"
  excludedVersionIds={[123, 456]}
>
  {/* Your app */}
</YouVersionProvider>

If you omit a permit list, that list applies no restriction. An empty permit list ([]) permits nothing. If a version is both permitted and excluded, exclusion wins.

The version filter applies to the version picker, recents, the reader, cards, text, Verse of the Day, and any versionId you pass. The SDK does not substitute another version, including 3034. Recents that fail the filter stay hidden until you change the filter. The SDK does not delete them.

---

Components

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

BibleCard, BibleTextView, BibleReader.Root, and VerseOfTheDay accept scriptureDirection to override the direction of Bible content. Omit it to use passage direction, with browser detection as the fallback. See Text direction.

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 = {
  /** Scripture direction override. Omit for automatic direction. */
  scriptureDirection?: "ltr" | "rtl";
  /** 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;
  /** Max BibleCard width in CSS px, or `"100%"` to expand to the full width of the parent container (defaults to 700) */
  maxWidth?: number | "100%";
};

---

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 = {
  /** Scripture direction override. Omit for automatic direction. */
  scriptureDirection?: "ltr" | "rtl";
  /** 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 = {
  /** Scripture direction override. Omit for automatic direction. */
  scriptureDirection?: "ltr" | "rtl";
  /** 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";

  /** Fires on every verse selection change. Fires with `verses: []` when the selection clears. */
  onVerseSelect?: (selection: BibleReaderVerseSelection) => void;

  children?: ReactNode;
};

type BibleReaderVerseSelection = {
  /** Bible version identifier */
  versionId: number;
  /** USFM book code (e.g., "JHN") */
  book: string;
  /** Chapter id (e.g., "3") */
  chapter: string;
  /** Selected verse numbers, ascending and de-duplicated. Empty on clear. */
  verses: number[];
  /** Per-verse USFM ids (e.g., ["JHN.3.16", "JHN.3.17"]). Never ranges. */
  passageIds: string[];
};

See Highlights for setup and behavior.

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 = {
  /** Scripture direction override. Omit for automatic direction. */
  scriptureDirection?: "ltr" | "rtl";
  /** 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[];
  /** 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']} />