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

Verse images

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.
npm install @youversion/platform-core@2.17.0

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
import { useEffect, useState } from "react"; import { ApiClient, ImagesClient, type Collection, type VerseImage, } from "@youversion/platform-core"; const images = new ImagesClient(new ApiClient({ appKey: "YOUR_APP_KEY" })); function renditionUrl(image: VerseImage, size: "thumb" | "card" | "full"): string { const url = new URL(image.image_url); url.searchParams.set("size", size); return url.toString(); } export function PassageImages({ passageId, language }: { passageId: string; language: string }) { const [page, setPage] = useState<Collection<VerseImage> | null>(null); const [error, setError] = useState<Error | null>(null); useEffect(() => { let cancelled = false; setPage(null); setError(null); images .getImages({ passage_id: passageId, language_ranges: [language], page_size: 12, }) .then(async (nextPage) => { while (!cancelled && nextPage.data.length === 0 && nextPage.next_page_token !== null) { nextPage = await images.getImages({ passage_id: passageId, language_ranges: [language], page_size: 12, page_token: nextPage.next_page_token, }); } if (!cancelled) setPage(nextPage); }) .catch((cause: unknown) => { if (!cancelled) { setError(cause instanceof Error ? cause : new Error("Image request failed")); } }); return () => { cancelled = true; }; }, [passageId, language]); if (error) return <p>Could not load images. {error.message}</p>; if (!page) return <p>Loading images.</p>; if (page.data.length === 0) return <p>No images for this passage.</p>; return ( <ul> {page.data.map((image) => ( <li key={image.id}> <img src={renditionUrl(image, "thumb")} alt={`Verse image for ${image.passage_id}`} width={image.width} height={image.height} style={{ width: "100%", height: "auto", maxWidth: "20rem" }} /> <p>{image.attribution}</p> </li> ))} </ul> ); }

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
import { useEffect, useState } from "react"; import { ApiClient, BibleClient, ImagesClient, type VOTDResponse, type VerseImage, } from "@youversion/platform-core"; const apiClient = new ApiClient({ appKey: "YOUR_APP_KEY" }); const bible = new BibleClient(apiClient); const images = new ImagesClient(apiClient); type DailyArt = { verse: VOTDResponse; image: VerseImage | null }; export function DailyVerseImage({ day, language }: { day: number; language: string }) { const [result, setResult] = useState<DailyArt | null>(null); const [error, setError] = useState<Error | null>(null); useEffect(() => { let cancelled = false; setResult(null); setError(null); async function load() { try { const verse = await bible.getVOTD(day, { language_ranges: [language] }); const image = verse.image_id === null ? null : await images.getImage(verse.image_id); if (!cancelled) setResult({ verse, image }); } catch (cause: unknown) { if (!cancelled) { setError(cause instanceof Error ? cause : new Error("Daily image request failed")); } } } void load(); return () => { cancelled = true; }; }, [day, language]); if (error) return <p>Could not load the daily image. {error.message}</p>; if (!result) return <p>Loading the daily image.</p>; const url = result.image ? new URL(result.image.image_url) : null; url?.searchParams.set("size", "card"); return ( <section> <p>Verse of the Day: {result.verse.passage_id}</p> {result.image && url && ( <figure> <img src={url.toString()} alt={`Verse image for ${result.verse.passage_id}`} width={result.image.width} height={result.image.height} style={{ maxWidth: "100%", height: "auto" }} /> {result.image.attribution && <figcaption>{result.image.attribution}</figcaption>} </figure> )} </section> ); }

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.

Last modified on November 17, 2026
SearchMigration from Legacy Authentication
On this page
  • Requirements
  • List images for a passage
  • Load one image
  • Show Verse of the Day art
React
React