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.

transform defaults to true and is forwarded to getPassage. When format is "html", the hook returns sanitized, transformed HTML.

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,
    transform: true,
  });

  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;
  transform?: boolean;
  options?: UseApiDataOptions;
};

export function usePassage({
  versionId,
  usfm,
  format = "html",
  include_headings = false,
  include_notes = false,
  transform = true,
  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

Search hooks

useBibleSearch manages trending queries, debounced suggestions, verse results, pagination, and retries. useSearchClient returns the core search client for direct requests. See the search guide for a custom interface and the hook's search phases.

useUnifiedSearch

Retrieve top results across content kinds, such as verse references and related topics, in one request inside YouVersionProvider. Unlike useBibleSearch, this hook has no suggestions, input debounce, or pagination. See the unified search example.

Arguments: useUnifiedSearch(props, apiOptions?)

• props (UseUnifiedSearchProps): Required query, versionId, and languageRanges; optional userIntent and fields. These have the same meanings as the core searchUnified parameters.
• apiOptions (UseApiDataOptions, optional):
  • enabled (boolean, default true): Set to false until the query is ready. While disabled, data and error are null, and loading is false.
  • keepPreviousData (boolean, default true): Keep the previous result while changed inputs load. Set to false to clear it instead.

Return value: UseUnifiedSearchResult

• data: SearchUnifiedResponse or null. Contains verses, topics, images, didYouMean, searchInsteadFor, and optional userIntent. Image hits have { id: string; passageId: string }; image selection requires backend support. Verse hits contain passage IDs, not text.
• loading: Whether the current inputs are waiting for their results. A background refresh of settled data does not set this to true.
• error: Error or null.
• refetch(): Request fresh results for the current enabled query, such as after an error.

Changes to the query, Bible version, language preferences, intent, or result kinds select a new result set. Your interface controls when to apply those inputs.