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
React Native (Expo) SDK
    Quick StartComponentsSearchVerse imagesAuthentication
    Guides
React Native (Expo) SDK

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 Native Expo 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, Kotlin, and Swift.

Use useImages from @youversion/platform-react-native-expo-core to load verse art. Call it under YouVersionProvider.

Requirements

Paginated image search and selected Verse of the Day art require version 2.3.0 or later of both SDK packages.

useImages 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
npx expo install @youversion/platform-react-native-expo-ui@2.3.0 @youversion/platform-react-native-expo-core@2.3.0

List images

list returns the art for a passage that you already know. To find art that matches freeform text, such as "love", use image search instead.

Code
import { useImages } from "@youversion/platform-react-native-expo-core"; import { Button } from "react-native"; export function ListVerseImages() { const images = useImages(); return ( <Button title="List images" onPress={async () => { const listed = await images.list({ passage_id: "JHN.3.16", language_ranges: ["en"], }); if (listed.ok && listed.value.data[0]) { const image = listed.value.data[0]; const separator = image.image_url.includes("?") ? "&" : "?"; const url = `${image.image_url}${separator}size=thumb`; const attribution = image.attribution; } }} /> ); }

list and get each return { ok: true, value } or { ok: false, error }. An HTTP failure does not throw. A call cannot be aborted. Ignore a result that arrives after the screen unmounts or after the inputs change.

list returns a YouVersionImagePage. get returns a YouVersionImage. Use image_url to display the image.

Set the size query parameter on image_url to thumb, card, or full, preserving any existing query parameters. Omit size for the full image.

attribution is an optional credit line you can show next to the image. It can be an empty string. width and height are the full-size pixel counts.

list already includes the full record, so call get only when you have an id and not the record, such as an image from search results.

A passage_id filter is one verse, such as JHN.3.16, or a verse range, such as JHN.3.16-17. A chapter id such as JHN.3 fails with invalid-parameter.

The shared rules for sizes and passage filters are in Verse Images.

MethodParametersValue
listoptional passage_id, language_ranges, page_size, page_tokenA YouVersionImagePage with data, next_page_token, and optional total_size. Each item is a YouVersionImage with id, image_url, passage_id, attribution, language_tag, width, height, and aspect_ratio.
getimageIdOne YouVersionImage with those same fields.

page_size is an integer from 1 to 99. When you omit it, the API uses 25. language_ranges is an array of language tags, such as ["en"]. Omit language_ranges to include every language.

A regional tag such as en-US or es-MX returns an empty page and does not fall back to en or es. Send a base tag such as en instead. For Chinese art, pass zh-CN, zh-TW, or zh-HK.

When next_page_token is a string, pass it as page_token on the next list call, and keep the same passage_id and language_ranges. You can change page_size. null means there is no further page.

total_size, when present, is the total number of matching images.

If no images match, list returns an empty data list.

Load one image

Use an id from search or Verse of the Day to load an image. Render this component under YouVersionProvider:

Code
import { useImages } from "@youversion/platform-react-native-expo-core"; import { Button } from "react-native"; export function LoadImage({ imageId }: { imageId: string }) { const images = useImages(); return ( <Button title="Load image" onPress={async () => { const result = await images.get(imageId); if (result.ok) console.log(result.value.image_url); }} /> ); }

Pass an image id as imageId. See Load an image from search results.

On failure, result.error.kind is auth, not-found, invalid-parameter, or transient.

Show Verse of the Day art

Use useVerseOfTheDay under YouVersionProvider to request the day's passage and selected image. Pass language ranges in order of preference, then resolve a non-null image_id with useImages().get.

Code
import { useImages, useVerseOfTheDay } from "@youversion/platform-react-native-expo-core"; import { Button } from "react-native"; export function LoadDailyArt({ languageRanges }: { languageRanges: string[] }) { const verseOfTheDay = useVerseOfTheDay(); const images = useImages(); return ( <Button title="Load daily art" onPress={async () => { const day = await verseOfTheDay.get(1, { languageRanges }); if (!day.ok) return; console.log(day.value.passage_id); if (day.value.image_id !== null) { const image = await images.get(day.value.image_id); if (image.ok) console.log(image.value.image_url); } else { // No image is available for this day. } }} /> ); }

This example requests January 1 and logs the passage identifier and, when available, the selected image URL. Use image_url to display the art with your image component. image_id is null when no art matches the requested languages.

If you do not provide languageRanges, you get no image data. See Images in Verse of the Day for language selection. To request the full year's calendar, call verseOfTheDay.list with the same languageRanges. A successful result contains records in value.data.

Both methods return { ok: true, value } or { ok: false, error }. Ignore responses after the screen unmounts or its inputs change.

Last modified on November 17, 2026
SearchAuthentication
On this page
  • Requirements
  • List images
  • Load one image
  • Show Verse of the Day art
React
React
React