BibleReader includes Search on iOS and Android. Use useSearch from @youversion/platform-react-native-expo-core for suggested queries, trending queries, verses, images, and topics. Use useUnifiedSearch for one response with verse, topic, and image results.
Requirements
Paginated image search and selected Verse of the Day art require version 2.3.0 or later of both SDK packages.
useUnifiedSearch requires version 2.2.0 or later of @youversion/platform-react-native-expo-ui and @youversion/platform-react-native-expo-core. Install both packages together, at the same version. The UI package depends on one core version. Two copies of core make the hook throw.
expo
BibleReader
Search opens from the reader toolbar.
showToolbar={false} hides Search with the rest of the toolbar.
A verse result opens that chapter and focuses the verse. On initial load, the other verses are dimmed. A chapter result opens the chapter.
useSearch
Code
Each method returns { ok: true, value } or { ok: false, error }. An HTTP failure does not throw. These calls go to the Platform API. They do not read or write the on-device Bible content cache.
| Method | Parameters | Value |
|---|---|---|
suggestedQueries | query, languageRanges | { queries }. A query includes text. |
trendingQueries | languageRanges | { queries }. A query includes text. |
verses | query, bibleId, and optional userIntent, pageSize, pageToken | verses, userIntent, didYouMean, searchInsteadFor, and nextPageToken. Each verse id is a passage id such as JHN.3.16. |
images | query, bibleId, and optional pageSize, pageToken | images and nextPageToken. Each related image has an id and a passageId. |
topics | query, languageRanges | Topics with id (a number, or null), text, and subtopics. |
Pass languageRanges as an array, such as ["en"] or ["en-US", "en"]. See Language ranges for language selection and unsupported values. bibleId is the Bible version id.
For verses, images, and topics, query must be 1–100 characters. Optional pageSize on verses must be 1–99. When the response includes nextPageToken, pass that value back as pageToken on the next verses call, and keep the same query, bibleId, userIntent, and pageSize.
SEARCH_USER_INTENT is { reference, text, topical, unknown }. userIntent is a string. The SDK keeps a value it does not recognize.
If there are no suggested or trending queries, the result contains an empty queries list.
On failure, result.error.kind is auth, not-found, invalid-parameter, or transient.
Page through image results
Call useSearch under YouVersionProvider, then use search.images to find art that matches freeform text in one Bible version. To list the art for a passage that you already know, use useImages().list instead.
The following fragment loads one page at a time:
Code
Call loadImagePage(bibleId) from an event handler to load the first page. Check the returned result's ok value before reading value.images, and handle error on failure. Append each successful page's images to your results. To load another page, pass a non-null value.nextPageToken to loadImagePage(bibleId, token). To display a related image, pass its id to useImages().get, as shown in Load an image from search results.
Keep the query, Bible version, and page size unchanged between pages. pageSize accepts 1 through 99. Stop only when nextPageToken is null. An empty page can include a continuation token. A search might find no related images. bibleId selects the language searched.
Call unified search
Call the hook under YouVersionProvider.
The hook returns one set of results. There is no page token. Each hook you mount fetches on its own.
Code
The return value is a UseUnifiedSearchResult. data is a YouVersionUnifiedSearchResults or null. error is a SearchApiError or null.
Call refetch to send the request again. loading is true while the first request for the current query is in flight, and while refetch follows an error. After a success, refetch keeps the last results and leaves loading false.
The first argument is UseUnifiedSearchProps: query, bibleId, languageRanges, and optional userIntent and fields. languageRanges is one tag or a list of tags, such as "en" or ["en"]. fields is an optional list of YouVersionUnifiedSearchField values: verses, topics, and images. Omit fields to return all three kinds. userIntent is optional. Pass a value from SEARCH_USER_INTENT, or omit it and the service uses unknown. The response can carry a newer intent string, and the SDK keeps it on data.userIntent.
The second argument is UseUnifiedSearchOptions. keepPreviousData defaults to true, so while a new query loads, data still holds the previous result. Pass false to clear it during that load. enabled: false does not send a request. data is null, loading is false, and error is null. keepPreviousData does not keep the previous result while the hook is disabled.
A blank query, a query longer than 100 characters, an empty or invalid languageRanges, or an empty fields array does not send a request. data is null, loading is false, and error is null, even when keepPreviousData is true. That is not an invalid-parameter error.
See Language ranges for language matching and preferences.
images is always an array of YouVersionImageSearchResult. A search might find no related images. Each related image is { id, passageId }. passageId is a verse or a verse range, such as 1CO.13.4-7.
verses, topics, and didYouMean are always arrays on that result. searchInsteadFor is a string or null. A verse result id is a passage id such as JHN.3.16.
Load an image from search results
Code
Pass the related image's id to images.get to load the image. get returns not-found if no image matches the id.
When one.ok is true, one.value is a YouVersionImage. passageId on the related image and passage_id on that record are the same passage. Sizes and passage filters are in Verse Images. The rest of this endpoint is in Search APIs.
Parse a passage id
A verse result id is a passage id. An example is JHN.3.16.
Call biblePassageAnchorFromPassageId(passageId, versionId) to turn that id into { versionId, bookId, chapter, verse? }.
The function returns null when the string is not a chapter, a single verse, or a verse range.
A range returns only the start verse. JHN.3.16-17 returns verse 16.
Pass the original passage id as passageId on focusReference when the reader should keep the full range.
Accepted shapes are PSA.23, JHN.3.16, and JHN.3.16-17. The book id is three characters from A-Z and 0-9.