Use the Images APIs to show verse art for the Verse of the Day, a search query, or a passage. This guide covers the React SDK. For direct HTTP requests and the rules that apply to every platform, see Verse Images. For other SDKs, see the image guides for JavaScript, React Native Expo, Kotlin, and Swift.
Use ImagesClient to load verse art for a passage and display it with the returned image_url.
Create an ImagesClient with an ApiClient.
Requirements
These samples match @youversion/platform-core 2.17.0.
- An app key from platform.youversion.com.
List images for a passage
getImages lists the art for a passage that you already know. To find art that matches freeform text, such as "love", use image search instead.
Pass passage_id as one verse or a verse range, such as JHN.3.16 or JHN.3.16-18. Chapter IDs such as JHN.3 are not supported. To request art for a chapter, pass a verse range instead. Omit language_ranges to get every language, or pass base tags such as en. Regional tags such as en-US and es-MX return an empty page without falling back to the base language. For Chinese art, request zh-CN, zh-TW, or zh-HK instead of a base tag. See Language selection.
attribution is an optional credit line you can show beside each image. The API can send an empty string.
The sample clears the list when passageId changes and ignores a response that arrives after that. A slow request for the previous passage would otherwise replace the list you are showing.
PassageImages.tsx
getImages returns Collection<VerseImage>. VerseImage contains id, image_url, passage_id, attribution, language_tag, width, height, and aspect_ratio. aspect_ratio is the width divided by the height, as the API reports it.
width and height are the full-size pixel counts. The sample sets them on the image element so the browser can reserve the ratio. Choose the downloaded rendition with size: thumb, card, or full. Limit the displayed width in CSS. See Picking a size.
If no images match, getImages returns an empty data list. An empty page can still have a continuation token; the example follows those tokens before showing the missing-art message. total_size, when present, is the total number of matching images.
next_page_token is null on the last page. Pass it back as page_token, and keep the same passage_id and language_ranges.
Load one image
getImage loads one VerseImage by id.
A missing id throws. Call getHttpStatus from @youversion/platform-core when you need the HTTP status of that error.
Search loads related images from unified search with getImage. Verse Images documents sizes, language matching, and caching for the REST API.
Show Verse of the Day art
Use BibleClient.getVOTD with language_ranges to request the image selected for a day. This requires core 2.17.0 or later. useVerseOfTheDay does not accept this language option. The example below uses the core clients directly and does not need YouVersionProvider.
Replace YOUR_APP_KEY with your App Key. Render <DailyVerseImage day={1} language="en" /> to request January 1 with English art. The component shows the passage identifier and the selected art when one is available:
DailyVerseImage.tsx
The response has day, passage_id, and nullable image_id. image_id is null when no image is available for that day.
Pass a non-null image_id to getImage. Listing images for the same passage can return different art from the day's selection. See Images in Verse of the Day for language selection. To request the full year, call getAllVOTDs with the same language_ranges and read its data array.