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
useUnifiedSearchfor 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
useBibleSearchfrom@youversion/platform-react-hooksand 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:
Code
If you import the search hook directly, install the hooks package:
Code
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
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.
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
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
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
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
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
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()orselectSuggestion(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
versionIdrestarts 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:
trendingandsuggestingexposequeries,loading, and an optionalerror.searchingmeans the hook is waiting for the first visible results.resultsexposesversesandnextPage.nextPageis"none","available","loading", or"failed".emptymeans no results match the current search and filter.failedexposes 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:
- Create one
BibleReaderNavigationinstance and retain it across renders. - Pass that instance to
BibleReader.Rootthrough itsnavigationprop. - 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
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:
- Open Search from the reader toolbar. Your application's search interface should appear instead of the built-in popover.
- Submit a query.
- Select a result. Your search interface should close, and the reader should show the selected passage in its chapter.