YouVersion PlatformYouVersion Platform
PlatformContent LibraryDev Docs
CommunityPartnersSupport

YouVersion Platform

Build applications and integrate with the world's most popular Bible platform.

Platform Products

  • Platform Portal
  • Developer Documentation
  • App Management

Resources

  • Support
  • Press inquiries

Legal

  • Privacy Policy
  • Terms of Use

© 2026 YouVersion. All rights reserved.

  • Overview
  • API Reference
  • SDKs
  • Changelog
<  Back to Platform
SDK Introduction
Swift SDK
Kotlin SDK
JavaScript SDK
React SDK
    Quick StartComponentsHooks
    Guides
      Copyright & AttributionHighlightsSearchVerse imagesMigration from Legacy AuthenticationText directionTheming
React Native (Expo) SDK
Guides

Search

BibleReader.Toolbar includes search by default. Use this guide when you need a different layout or your own search interface.

Choose the customization that fits your application:

  • Unified search: Use useUnifiedSearch for top results across content kinds, such as verse references and related topics, in one request without pagination.
  • Search images: Load related images from unified search, or page through image results.
  • Move the search button: Place the SDK's search control outside the toolbar.
  • Custom search interface: Use useBibleSearch from @youversion/platform-react-hooks and render your own controls.
  • Host-owned reader search: Use your application's search interface in place of the reader's popover through onSearchPress.

Requirements

  • Get an App Key from YouVersion Platform.
  • Render search components and hooks inside YouVersionProvider. See the React quick start.

Install the UI package for reader search:

TerminalCode
npm install @youversion/platform-react-ui

If you import the search hook directly, install the hooks package:

TerminalCode
npm install @youversion/platform-react-hooks

Search verses and topics together

For a general search box, use useUnifiedSearch to retrieve top results in one request. This example selects verse references and related topics with fields.

You must supply both a Bible version ID and language preferences. The Bible version selects the text and language for verse results; the preferences select the language for topic and image results.

Use languageRanges: ["*"] to match all languages for topic and image results.

Render this component inside YouVersionProvider:

Code
import { useState } from "react"; import { useUnifiedSearch } from "@youversion/platform-react-hooks"; export function UnifiedSearch({ versionId, languageRanges, }: { versionId: number; languageRanges: string[]; }) { const [query, setQuery] = useState(""); const { data, loading, error, refetch } = useUnifiedSearch( { query, versionId, languageRanges, fields: ["verses", "topics"], }, { enabled: query.length > 0 } ); return ( <section aria-label="Search"> <form onSubmit={(event) => { event.preventDefault(); const form = new FormData(event.currentTarget); setQuery(String(form.get("query") ?? "").trim()); }} > <label> Search <input name="query" required /> </label> <button type="submit">Search</button> </form> {loading && <p role="status">Searching...</p>} {error && ( <p role="alert"> Search was unavailable. <button onClick={refetch}>Retry</button> </p> )} {!loading && !error && data && ( <> <h2>Verses</h2> <ul> {data.verses.map((verse) => ( <li key={verse.id}>{verse.id}</li> ))} </ul> <h2>Topics</h2> <ul> {data.topics.map((topic) => ( <li key={topic.text}>{topic.text}</li> ))} </ul> {data.verses.length === 0 && data.topics.length === 0 && ( <p>No results found.</p> )} </> )} </section> ); }

Typing in this example does not send a request. Submitting the form updates the query; enabled prevents an empty query from loading. The hook does not manage a search field.

Other features you might want to add include input debouncing, search suggestions, and trending queries.

Omit fields to request all available result kinds; do not pass an empty array. See the core searchUnified parameters for currently supported kinds.

Use useBibleSearch for the paginated verse-search workflow. Unified search returns only top results, with no Load more action. It does not change the reader's built-in search. Verse results contain passage IDs, not passage text; display a selected passage with BibleCard.

For options and return fields, see the useUnifiedSearch reference. For language selection, see Language ranges.

Search images

Use useUnifiedSearch to find related images with verse and topic results, then load each image with ImagesClient.getImage.

These samples match @youversion/platform-react-hooks 2.17.0 and @youversion/platform-core 2.17.0. The hooks package depends on that core release. Import ImagesClient from @youversion/platform-core.

npm install @youversion/platform-react-hooks@2.17.0 @youversion/platform-core@2.17.0

Pass query, versionId, and languageRanges. Both settings are required because they select different results. versionId picks the Bible version for verse results, and that version sets their language. languageRanges supplies the search language for topic and image results.

languageRanges is an ordered list of basic language ranges, such as ["en"]. See Language ranges for matching rules and preferences.

The sample does not render data while loading is true. data can still hold the previous response during a new query, so this keeps images from the previous query off the screen.

Load an image from search results

ImagesClient.getImage loads the VerseImage for a related image's id. Construct the client with new ImagesClient(new ApiClient({ appKey })). That client uses the app key and does not read YouVersionProvider.

The sample shows the optional attribution credit line with each image. If the related image changes before getImage resolves, the effect drops the late record.

UnifiedSearch.tsx
import { useEffect, useState } from "react"; import { ApiClient, ImagesClient, type SearchImageHit, type SearchUnifiedResponse, type VerseImage, } from "@youversion/platform-core"; import { useUnifiedSearch, YouVersionProvider } from "@youversion/platform-react-hooks"; const appKey = "YOUR_APP_KEY"; const images = new ImagesClient(new ApiClient({ appKey })); function renditionUrl(image: VerseImage, size: "thumb" | "card" | "full"): string { const url = new URL(image.image_url); url.searchParams.set("size", size); return url.toString(); } function hasNoResults(data: SearchUnifiedResponse): boolean { return data.verses.length === 0 && data.topics.length === 0 && data.images.length === 0; } function UnifiedImage({ relatedImage }: { relatedImage: SearchImageHit }) { const [image, setImage] = useState<VerseImage | null>(null); const [error, setError] = useState<Error | null>(null); useEffect(() => { let cancelled = false; setImage(null); setError(null); images .getImage(relatedImage.id) .then((nextImage) => { if (!cancelled) setImage(nextImage); }) .catch((cause: unknown) => { if (!cancelled) { setError(cause instanceof Error ? cause : new Error("Image request failed")); } }); return () => { cancelled = true; }; }, [relatedImage.id]); if (error) return <p>Could not load this image. {error.message}</p>; if (!image) return <p>Loading image.</p>; return ( <figure> <img src={renditionUrl(image, "card")} alt={`Verse image for ${image.passage_id}`} width={image.width} height={image.height} style={{ width: "100%", height: "auto", maxWidth: "40rem" }} /> <figcaption> {image.attribution} {image.passage_id} </figcaption> </figure> ); } function UnifiedResults({ query, versionId, languageRanges, }: { query: string; versionId: number; languageRanges: string[]; }) { const { data, loading, error } = useUnifiedSearch({ query, versionId, languageRanges, }); if (loading) return <p>Loading results.</p>; if (error) return <p>Search was unavailable. {error.message}</p>; if (!data) return null; if (hasNoResults(data)) return <p>No results.</p>; return ( <div> {data.searchInsteadFor ? <p>Showing results for {data.searchInsteadFor}.</p> : null} <ul> {data.verses.map((verse) => ( <li key={verse.id}>{verse.id}</li> ))} </ul> <ul> {data.topics.map((topic) => ( <li key={`${topic.id ?? "topic"}-${topic.text}`}>{topic.text}</li> ))} </ul> {data.images.map((relatedImage) => ( <UnifiedImage key={relatedImage.id} relatedImage={relatedImage} /> ))} </div> ); } export function SearchExample() { return ( <YouVersionProvider appKey={appKey}> <UnifiedResults query="love" versionId={3034} languageRanges={["en"]} /> </YouVersionProvider> ); }

Options and response details

userIntent is optional. The values are unknown, topical, text, and reference. Omit it to use the service default, unknown.

fields is optional. The values are verses, topics, and images. Omit fields to request every kind.

The hook returns data, loading, error, and refetch. data is SearchUnifiedResponse or null. To clear data when a new query starts, pass { keepPreviousData: false } as the second argument.

The hook skips the request when query is empty or longer than 100 characters, when languageRanges is empty or invalid, or when fields is empty. data and error are then null, and loading is false.

A verse result id is a USFM passage id, such as JHN.3.16. It is not the verse text. Load the text from the passages API.

A related image has id and passageId. didYouMean contains alternate spellings, or an empty array when there are none.

Use the returned image_url to display the image. Select thumb, card, or full with the size query parameter. See Picking a size.

Unified search is not paginated. For a full verse page, call searchVerses on the client from useSearchClient. For a full topic list, call searchTopics. To page through related images, call searchImages on the client returned by useSearchClient. See Page through image results.

Page through image results

Use searchImages to find art that matches freeform text when you need more images than unified search returns. To list the art for a passage that you already know, use getImages instead. searchImages requires core 2.17.0 or later. The Bible version selects the search language.

This component searches for love in Bible version 3034. Render it inside YouVersionProvider, as shown in the React quick start:

ImageSearchPages.tsx
import { useState } from "react"; import type { SearchImageHit, SearchImagesResponse } from "@youversion/platform-core"; import { useSearchClient } from "@youversion/platform-react-hooks"; export function ImageSearchPages() { const search = useSearchClient(); const [relatedImages, setRelatedImages] = useState<SearchImageHit[]>([]); const [page, setPage] = useState<SearchImagesResponse | null>(null); const [loading, setLoading] = useState(false); const [error, setError] = useState<Error | null>(null); const finished = page !== null && page.nextPageToken === null; const load = async () => { const pageToken = page?.nextPageToken; if (loading || pageToken === null) return; setLoading(true); setError(null); try { const nextPage = await search.searchImages("love", 3034, { pageSize: 25, ...(pageToken === undefined ? {} : { pageToken }), }); setRelatedImages((current) => [...current, ...nextPage.images]); setPage(nextPage); } catch (cause: unknown) { setError(cause instanceof Error ? cause : new Error("Image search was unavailable")); } finally { setLoading(false); } }; return ( <section aria-label="Image search results"> <ul> {relatedImages.map((relatedImage, index) => <li key={index}>{relatedImage.passageId}</li>)} </ul> {finished && relatedImages.length === 0 && <p>No images found.</p>} {error && <p role="alert">Could not load images. {error.message}</p>} <button disabled={loading || finished} onClick={load}> {loading ? "Loading images" : page === null ? "Search images" : "Load more"} </button> </section> ); }

Choose Search images to list matching passage identifiers, then Load more to append the next page. Each related image also has an id. Pass it to ImagesClient.getImage to display the art, as in Load an image from search results.

Keep the query, Bible version, and page size unchanged between pages. A page with no images can still include a continuation token. Stop only when nextPageToken is null. The example disables its button while a request is in progress. If you add query or Bible-version controls, clear the accumulated images and ignore responses from the previous search when those inputs change.

Read the search client

useSearchClient returns the SearchClient created for the provider. Use it for searchVerses, searchTopics, and searchImages. Related images from unified search still go through ImagesClient.getImage, as in Load an image from search results.

Code
import { useState } from "react"; import { useSearchClient, YouVersionProvider } from "@youversion/platform-react-hooks"; function VerseSearchPage() { const search = useSearchClient(); const [verseIds, setVerseIds] = useState<string[] | null>(null); const [error, setError] = useState<Error | null>(null); const load = async () => { try { const page = await search.searchVerses("love", 3034, { pageSize: 25 }); setVerseIds(page.verses.map((verse) => verse.id)); setError(null); } catch (cause: unknown) { setError(cause instanceof Error ? cause : new Error("Verse search was unavailable")); } }; return ( <div> <button onClick={() => void load()}>Load verses</button> {error ? <p>{error.message}</p> : null} {verseIds && verseIds.length === 0 ? <p>No verses.</p> : null} {verseIds && verseIds.length > 0 ? <p>{verseIds[0]}</p> : null} </div> ); } export function VerseSearchExample() { return ( <YouVersionProvider appKey="YOUR_APP_KEY"> <VerseSearchPage /> </YouVersionProvider> ); }

Replace YOUR_APP_KEY with your app key from the React quick start.

The request and response fields for every search endpoint are in Search APIs. Listing art for a passage, without search, is in Verse images.

Move the search button

BibleReaderSearch renders a search icon button that opens a popover with a search field and results. Use it when your layout needs the search button outside the toolbar, such as above the passage while chapter controls remain below it.

Render BibleReaderSearch inside BibleReader.Root. Set search="none" on the toolbar to avoid showing two search buttons:

Code
import { BibleReader, BibleReaderSearch } from "@youversion/platform-react-ui"; function Reader() { return ( <BibleReader.Root defaultVersionId={3034}> <BibleReaderSearch /> <BibleReader.Content /> <BibleReader.Toolbar search="none" /> </BibleReader.Root> ); }

BibleReaderSearch must remain inside BibleReader.Root, and the reader must remain inside YouVersionProvider.

To control the popover's visibility, use these optional props:

  • open: The current open state when your application controls visibility.
  • onOpenChange: A callback that receives changes to the open state.
  • defaultOpen: The initial open state when the component controls visibility.

Build a custom search interface

Import useBibleSearch from @youversion/platform-react-hooks. The hook takes a versionId and an optional bookIds filter.

Save this component as VerseSearch.tsx. It lists passage identifiers and calls onSelect when the user chooses one.

Render the component inside YouVersionProvider, and use onSelect to display the passage or navigate to it. The host-owned search example connects this component to reader navigation.

VerseSearch.tsx
import { useBibleSearch } from "@youversion/platform-react-hooks"; type VerseSearchProps = { versionId: number; onSelect: (passageId: string) => void; }; export function VerseSearch({ versionId, onSelect }: VerseSearchProps) { const search = useBibleSearch({ versionId }); const { phase } = search; return ( <section aria-label="Bible search"> <form onSubmit={(event) => { event.preventDefault(); search.submit(); }} > <label> Search the Bible <input value={search.query} onChange={(event) => search.setQuery(event.target.value)} /> </label> <button type="submit" disabled={!search.query.trim()}> Search </button> </form> {(phase.kind === "trending" || phase.kind === "suggesting") && ( <> {phase.loading && <p role="status">Loading queries...</p>} {phase.error && ( <p role="alert"> Could not load queries.{" "} <button onClick={search.retry}>Retry</button> </p> )} <ul aria-label="Search queries"> {phase.queries.map((query) => ( <li key={query.text}> <button onClick={() => search.selectSuggestion(query.text)}> {query.text} </button> </li> ))} </ul> </> )} {phase.kind === "searching" && <p role="status">Searching...</p>} {phase.kind === "empty" && <p role="status">No verses found.</p>} {phase.kind === "failed" && ( <p role="alert"> Search was unavailable. <button onClick={search.retry}>Retry</button> </p> )} {phase.kind === "results" && ( <> <ul aria-label="Search results"> {phase.verses.map((verse) => ( <li key={verse.id}> <button onClick={() => onSelect(verse.id)}>{verse.id}</button> </li> ))} </ul> {phase.nextPage === "available" && ( <button onClick={search.loadMore}>Load more</button> )} {phase.nextPage === "loading" && ( <p role="status">Loading more results...</p> )} {phase.nextPage === "failed" && ( <p role="alert"> Could not load more results.{" "} <button onClick={search.retry}>Retry</button> </p> )} </> )} </section> ); }

Query lifecycle

  • setQuery(raw) updates the input and truncates it to 100 characters. The hook trims the text used for requests.
  • If the query is empty, the hook requests trending queries. For nonempty input, the hook waits 300 ms for typing to pause before requesting suggestions. This delay is called a debounce.
  • submit() or selectSuggestion(text) starts verse search. Typing alone does not request verse results.
  • Changing the normalized query (the trimmed input) returns to suggestions or trending queries. Changing versionId restarts the submitted search in the new Bible version.
  • Suggestions and trending queries use the Bible version's language tag. If the tag is missing or invalid, the hook uses * to match all languages. See Language ranges.

Search phases

The hook returns a phase object. Read phase.kind before accessing that phase's fields:

  • trending and suggesting expose queries, loading, and an optional error.
  • searching means the hook is waiting for the first visible results.
  • results exposes verses and nextPage. nextPage is "none", "available", "loading", or "failed".
  • empty means no results match the current search and filter.
  • failed exposes the initial search error.

The suggesting phase also exposes debouncing. This field describes pending input, not a network request. Use loading, not debouncing, for a network-loading indicator.

If a later page fails, the hook keeps the existing results and sets nextPage to "failed". retry() retries failed query suggestions, the initial search, or the failed results page.

Results and book filters

Each result contains a passage id in Unified Standard Format Markers (USFM) reference format, a book, a chapter, and an array of verse numbers. The hook removes duplicate passage IDs and omits chapter-only results.

The hook does not return passage text. Fetch text with usePassage, or display a selected result with BibleCard, which includes attribution.

The hook requests pages of 20 results and accumulates results when you call loadMore().

Pass bookIds, such as ["JHN"], to filter by book. Filtering happens in the client, not in the search request.

If no matching results are visible and bookIds contains at least one book, the hook automatically requests more pages until it finds a match or reaches the end.

Once matching results are visible, a loadMore() call can add no visible results if the next page contains no matches. If nextPage is "available", call loadMore() again to request another page.

  • To include all books, omit bookIds.
  • To include no books, pass [].

useBibleSearch does not expose topic search, search intent, or query-correction metadata; use useUnifiedSearch for those. For direct requests, use useSearchClient() inside the provider and call the methods in the TypeScript search guide. Manage loading, results, and errors in your interface for these direct calls.

Connect host-owned search to the reader

If your application owns the search interface, pass onSearchPress to BibleReader.Root. This callback replaces the built-in popover and receives the reader's current versionId, book, and chapter. Returning a value from the callback does not navigate the reader.

Connect your interface to reader navigation:

  1. Create one BibleReaderNavigation instance and retain it across renders.
  2. Pass that instance to BibleReader.Root through its navigation prop.
  3. When the user selects a result, call focusReference({ versionId, passageId }) on the navigation instance.

The example below reuses VerseSearch.tsx from the custom search section. Replace YOUR_APP_KEY with your App Key:

App.tsx
import { useState } from "react"; import { BibleReader, BibleReaderNavigation, YouVersionProvider, } from "@youversion/platform-react-ui"; import { VerseSearch } from "./VerseSearch"; export default function App() { const [navigation] = useState(() => new BibleReaderNavigation()); const [searchVersionId, setSearchVersionId] = useState<number | null>(null); return ( <YouVersionProvider appKey="YOUR_APP_KEY"> {searchVersionId !== null && ( <section aria-label="Reader search"> <button onClick={() => setSearchVersionId(null)}>Close search</button> <VerseSearch key={searchVersionId} versionId={searchVersionId} onSelect={(passageId) => { navigation.focusReference({ versionId: searchVersionId, passageId, }); setSearchVersionId(null); }} /> </section> )} <div style={{ height: "100svh" }}> <BibleReader.Root defaultVersionId={3034} navigation={navigation} onSearchPress={({ versionId }) => setSearchVersionId(versionId)} > <BibleReader.Content /> <BibleReader.Toolbar /> </BibleReader.Root> </div> </YouVersionProvider> ); }

focusReference({ versionId, passageId }) opens the full chapter, scrolls to the passage, and temporarily emphasizes its verses. It does not create a saved highlight. If you request navigation before the reader mounts, the connection retains the newest pending request for mounting.

Pass the original result id as passageId to preserve a verse range. For example, JHN.3.16-18 focuses verses 16 through 18, not only verse 16. You do not need to parse the identifier before calling focusReference.

To check this integration:

  1. Open Search from the reader toolbar. Your application's search interface should appear instead of the built-in popover.
  2. Submit a query.
  3. Select a result. Your search interface should close, and the reader should show the selected passage in its chapter.
Last modified on November 17, 2026
HighlightsVerse images
On this page
  • Requirements
  • Search verses and topics together
  • Search images
    • Load an image from search results
    • Options and response details
  • Page through image results
  • Read the search client
  • Move the search button
  • Build a custom search interface
    • Query lifecycle
    • Search phases
    • Results and book filters
  • Connect host-owned search to the reader
React
React
React
React
React
React
React