React SDK

Hooks

Copy page

Installation

---

Authentication Hooks

useYVAuth

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

Code
import { useYVAuth } from "@youversion/platform-react-hooks";

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

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

  if (!auth.isAuthenticated) {
    return (
      <button onClick={() => signIn({ scopes: ['email', 'profile'] })}>
        Sign In
      </button>
    );
  }

  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 = {
  /** Current authentication state (isAuthenticated, isLoading, tokens, error) */
  auth: AuthenticationState;
  /** User profile extracted from JWT tokens, or null if not authenticated */
  userInfo: YouVersionUserInfo | null;
  /** Sign out the current user */
  signOut: () => void;
  /** Programmatically trigger sign-in. Not needed if using YouVersionAuthButton. */
  signIn: (params?: {
    redirectUrl?: string;
    scopes?: AuthenticationScopes[];
  }) => Promise<void>;
  /** Process the OAuth callback. YouVersionProvider handles this automatically — only needed for custom callback page implementations. */
  processCallback: () => Promise<SignInWithYouVersionResult | null>;
  /** The authRedirectUrl configured on YouVersionProvider. Read-back convenience — rarely needed directly. */
  redirectUri?: string;
};

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,
    format: "html",
    include_headings: true,
    include_notes: false,
  });

  if (loading) return <div>Loading...</div>;

  return (
    <div>
      <h2>{passage?.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().getTime() - new Date(new Date().getFullYear(), 0, 0).getTime()) / 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"] as string}</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